hf-model-inference

HuggingFace 模型推理服务

概述

本技能提供设置 HuggingFace 模型推理服务的操作指南，涵盖模型下载、缓存策略、Flask API 创建以及服务部署模式。

工作流

阶段 1：环境设置

1. 确认包管理器可用

   • 安装依赖前，检查是否有 uv、pip 或 conda
   • 如果可用，优先使用 uv，以加快依赖解析速度

2. 安装所需软件包

   • 核心：transformers、torch（或 tensorflow）
   • API：用于 REST 端点的 flask
   • 安装大型软件包时设置适当的超时时间（300 秒以上）

3. 创建模型缓存目录

   • 为模型存储建立专用目录（例如 /app/model_cache/model_name）
   • 下载前按需创建父目录

阶段 2：模型下载

1. 单独下载模型，不要在 API 启动时下载

   • 使用专用下载脚本，或在启动服务前直接下载
   • 这样可以避免 API 初始化期间出现超时问题

2. 明确指定缓存目录

   from transformers import pipeline
   model = pipeline("task-type", model="model-name", cache_dir="/path/to/cache")
   

3. 验证步骤（经常被遗漏）

   • 下载后，确认目标目录中存在模型文件
   • 列出目录内容，确认下载成功

阶段 3：API 创建

1. Flask 应用结构

   from flask import Flask, request, jsonify
   from transformers import pipeline
   
   app = Flask(__name__)
   model = None  # Load at startup
   
   @app.route('/predict', methods=['POST'])
   def predict():
       # Handle inference
       pass
   

2. 输入验证要求

   • 检查请求 JSON 中是否包含必填字段
   • 验证字段类型（字符串、数字等）
   • 处理空输入或仅包含空白字符的输入
   • 返回描述性错误消息，并使用适当的 HTTP 状态码

3. 错误响应格式

   • 使用一致的 JSON 结构：{"error": "message"}
   • 客户端错误返回 400，服务端错误返回 500

阶段 4：服务部署

1. 主机和端口配置

   • 绑定到 0.0.0.0，以便外部访问
   • 使用指定端口（通常为 5000）
   • 示例：app.run(host='0.0.0.0', port=5000)

2. 后台运行

   • 测试时在后台模式下启动 Flask
   • 发送测试请求前，留出启动时间（2-3 秒）

验证策略

模型下载验证

• 下载后列出缓存目录内容
• 确认预期的模型文件存在（config.json、模型权重、分词器文件）

API 功能测试

按以下顺序测试这些场景：

1. 正向场景：应能成功处理的有效输入

   curl -X POST http://localhost:5000/predict \
     -H "Content-Type: application/json" \
     -d '{"text": "valid input text"}'
   

2. 负向场景：使用另一种有效输入，验证响应有所不同

   curl -X POST http://localhost:5000/predict \
     -H "Content-Type: application/json" \
     -d '{"text": "different input text"}'
   

3. 错误场景：缺少必填字段

   curl -X POST http://localhost:5000/predict \
     -H "Content-Type: application/json" \
     -d '{}'
   

扩展边缘场景（可选）

• 空字符串输入
• 超长文本输入
• 非 JSON 内容类型
• 格式错误的 JSON
• 字段类型错误（数字而非字符串）

常见问题

安装问题

• 超时时间不足：torch 等大型软件包需要较长的超时时间（5 分钟以上）
• 缺少系统依赖项：某些模型需要额外的系统软件包

模型加载问题

• 冷启动超时：在首次请求时加载模型会导致超时；应改为在启动时加载
• 内存限制：大型模型可能超出可用 RAM；请检查模型要求

API 问题

• 开发服务器警告：Flask 开发服务器不适用于生产环境；可用于测试，但请注意此限制
• 缺少正常关闭机制：考虑添加信号处理，以便干净地终止进程
• 缺少健康检查端点：添加 /health 端点有助于调试

进程管理

• 后台进程验证：在后台启动后，确认进程正在运行
• 端口冲突：启动前检查指定端口是否已被占用

任务规划模板

处理 HuggingFace 推理任务时，请按以下结构安排工作：

1. 验证环境（包管理器、系统要求）
2. 使用合适的超时设置安装依赖项
3. 创建缓存目录
4. 下载模型并明确指定缓存路径
5. 验证模型下载
6. 创建 API 脚本并进行验证
7. 在后台启动服务
8. 功能测试（正向、负向和错误场景）
9. 边缘情况测试（如果时间允许）