Heroku部署Flask NLP模型本地正常 线上预测无结果如何排查

问题现状 #

• 已将搭载日文NLP处理能力的价格预测Flask应用部署至Heroku平台，模型输入包含日文文本字段、数值型字段两类
• 日文分词基于Nagisa库实现，训练完成的预测模型、文本向量化器均通过pickle序列化后集成到Flask API中
• 部署完成后前端输入参数点击Predict按钮无法正常返回预测结果，触发运行时错误
• 当前使用的日文分词函数实现如下：

def tokenize_jp(doc):
        doc = nagisa.tagging(doc)
        return doc.words

排查与修复方案 #

按优先级从高到低依次排查以下问题：

• 依赖版本不一致问题（最高发）
  本地训练环境与Heroku部署环境的依赖版本不匹配，会直接导致pickle序列化的模型/向量化器加载失败、自定义函数调用异常。重点核对nagisa、scikit-learn（sklearn向量化器/模型）、Python解释器的版本：

  注意：scikit-learn跨大/次版本加载pickle文件时，会出现自定义分词函数无法识别、模型属性缺失的报错。
  修复操作：本地执行pip freeze | grep -E "nagisa|scikit-learn|Flask|pandas"，把输出的精确版本号写入项目根目录的requirements.txt，重新推送代码到Heroku触发部署。

• 自定义分词函数作用域异常
  带自定义tokenizer参数的sklearn向量化器通过pickle序列化后，加载时要求当前运行环境的全局命名空间内能直接访问到同名的分词函数，否则会抛出函数找不到的错误。常见触发场景：分词函数定义在训练脚本的局部作用域、部署时函数嵌套在其他类/函数内部、跨脚本导入时未放到全局命名空间。
  修复操作：

  1. 把tokenize_jp函数写在Flask应用脚本的全局作用域，不要嵌套在其他函数、类内部
  2. 执行pickle加载操作前，确认当前代码可以直接调用tokenize_jp，不要给函数加会修改签名的装饰器
  3. 如果分词函数单独写在工具脚本里，要在加载pickle的代码前显式导入该函数到全局作用域

• Nagisa库Heroku运行适配问题
  Nagisa首次运行时会自动下载内置日文分词模型权重到本地存储，但Heroku的dyno文件系统是临时的，重启后文件会重置；如果构建阶段没有提前触发权重下载，运行时调用nagisa.tagging会因为权重缺失、目录无写入权限报错。
  修复操作：

  1. 在Flask应用启动逻辑中加入Nagisa预加载代码，服务启动时就触发权重下载和初始化，避免首次请求时加载失败：

  import nagisa
  # 服务启动前预加载Nagisa模型
  nagisa.tagging("テスト")
  

  2. 为Heroku应用开启构建缓存，避免每次dyno重启都重新下载权重文件

• 输入值类型/空值未做兜底
  前端传入的日文字段如果是空值、None、非字符串类型（比如数字类型），直接传入nagisa.tagging会触发类型错误。
  修复操作：给分词函数增加类型校验和空值兜底逻辑：

  def tokenize_jp(doc):
      # 非字符串、空内容直接返回空分词结果
      if not isinstance(doc, str) or len(doc.strip()) == 0:
          return []
      res = nagisa.tagging(doc)
      return res.words
  

  同时在接口接收参数的逻辑层，对所有数值型字段做类型转换校验，避免拼接特征矩阵时出现类型不匹配问题。

• pickle文件路径加载错误
  Heroku部署时的运行工作目录和本地开发环境不一致，如果用相对路径加载pickle序列化的模型、向量化器，很容易触发文件找不到的报错。
  修复操作：基于当前脚本的绝对路径拼接模型文件路径，不要写硬编码的相对路径：

  import os
  import pickle
  
  BASE_DIR = os.path.dirname(os.path.abspath(__file__))
  # 替换成你自己的pickle文件名
  vectorizer = pickle.load(open(os.path.join(BASE_DIR, "tfidf_vectorizer.pkl"), "rb"))
  model = pickle.load(open(os.path.join(BASE_DIR, "price_predict_model.pkl"), "rb"))
  

内容的提问来源于stack exchange，提问作者Pranjal Bisht