LabelHub Agent - AI 数据标注自动预审系统

本系统基于 FastAPI + Celery + OpenAI/LiteLLM 构建，旨在对标注员提交的数据进行自动化的 AI 预审。

Agent 设计与打分思路

1. 接入模型方式：LiteLLM + Function Calling

我们没有让大模型直接输出一大段文字（因为普通文本极难在代码里提取分数）。 我们使用了 LiteLLM 库（统一调度接口）和 Function Calling（函数调用/结构化输出） 技术。

• 机制：我们在发送请求时，会“欺骗”大模型说：“我这里有一个叫 submit_review_result 的函数，它必须接收三个参数：分数（scores）、评语（ai_comment）、结论（conclusion）。你阅读完数据后，请不要跟我聊天，直接去‘调用’这个函数，并填好这三个参数传给我。”
• 结果：大模型会直接返回一个标准的 JSON 数据结构，代码收到后可以直接转换成字典写入数据库。

2. 打分思路与流转流程

整个 Agent 的工作像一条流水线流水作业，分为四个关键步骤：

• 步骤 1：后台配发“考卷” (配置 Config)

  • 任务负责人预先定义好这批标注数据的评测标准（Prompt 模板）。
  • 同时规定好评分维度（例如：["relevance" (相关性), "accuracy" (准确性)]）。

• 步骤 2：自动拼装“试题” (Prompt 组装)

  • 标注员提交原始数据后，Celery 任务队列会接手。
  • Agent 将后台配置的 Prompt 模板与标注员刚刚提交的数据拼装在一起，形成最终发给大模型的完整指令。

• 步骤 3：多维度动态打分 (动态 Schema 生成)

  • Agent 代码会根据负责人配置的维度，动态生成要求大模型输出的 JSON 格式（JSON Schema）。
  • 例如配置了 2 个维度，Agent 就会强迫大模型分别对这 2 个维度各打一个 1-10 分。
  • 大模型除了给出各个维度的具体分数外，还会根据综合表现，强制输出 pass (通过) 或 return (打回人工复核) 的结论，并附带一句 AI 的综合评语（质检建议）。

• 步骤 4：入库与展示 (工作台展示)

  • 提取出大模型返回的 JSON 后，Agent 将分数、结论、评语以及当时的原始 Prompt 一并存入 ReviewResult 数据库表。
  • 审核人员可以在“审核工作台”直接查看这份“AI 体检报告”。

3. 预制模板库 (Preset Templates) 设计

为了兼顾“不懂技术、追求快而准”的老板，以及“要求严苛、需要精细化控制”的技术主管，系统内置了场景化预制模板：

• 系统内置了多种经典场景（包含文本场景与多模态图片场景，如：客服对话质检、内容安全审核、图片分类审核、OCR 校对 等）。
• 每个场景都预配了最符合该场景大模型胃口的 最佳实践 Prompt 以及 推荐的评分维度。
• 前端可以通过 /api/config/presets 接口获取这些预制模板，实现“一键导入，微调即用”。

4. 多模态 (多数据类型) 支持

系统不仅仅支持文本数据，还全面支持图片等多模态数据的审核：

• 提交接口支持区分类型：通过 data_type 字段可以区分提交的是纯文本 (text) 还是图片 (image_url)。
• 自动切换大模型 Vision 能力：如果提交的是图片 URL，Agent 会自动将数据组装为大模型所要求的 image_url 多模态格式发送给模型（需配合如 gpt-4o-mini 这样支持视觉的模型使用）。

核心功能

1. 多模态与多数据类型: 支持纯文本和图片(URL)等多种媒体类型的打标数据。
2. 可配置评测标准: 支持在后台配置审核 Prompt 模板与评分维度（如：相关性，准确性，格式合规安全性等）。
3. 预制模板库: 针对常见任务提供开箱即用的 Prompt 与维度推荐。
4. 自动化预审: 标注员提交数据后自动进入 Celery 异步队列。
5. 结构化打分: Agent 调用大模型（基于 Function Calling/结构化输出），按维度打分并给出结论（通过 / 打回人工复核）。
6. 审核工作台: 审核结果与原数据一并入库，可查看 AI 评语与原始 Prompt。
7. 高可用设计: 具备异步任务重试机制与幂等性保障。

技术栈

• 框架: FastAPI
• 异步队列: Celery + Redis
• 数据库: MySQL (基于 SQLAlchemy 2.0 + PyMySQL，支持高并发行级锁)
• AI 调用: LiteLLM (支持无缝切换 OpenAI, Gemini 等模型，强制结构化输出)

快速启动与测试指南

1. 环境准备

确保本地已安装 Python 3.10+，并运行了 Redis 服务（默认端口 6379）。 同时确保本地已安装并运行 MySQL (版本 5.7+ 即可，推荐 8.0+ 支持原生 JSON)，并在 MySQL 中提前创建好名为 labelhub 的数据库：

CREATE DATABASE labelhub CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

# 安装依赖
pip install -r requirements.txt

2. 配置密钥与数据库

在项目根目录修改 .env 文件，填入你选择的模型 API Key 以及你本地 MySQL 的账号密码：

OPENAI_API_KEY=sk-your_openai_key_here
GEMINI_API_KEY=your_gemini_key_here

# 替换 root:123456 为你的 MySQL 用户名和密码
DATABASE_URL=mysql+pymysql://root:123456@localhost:3306/labelhub

3. 启动服务

你需要开启两个终端窗口，分别启动 API 服务和异步队列：

# 终端 1：启动 API 服务 (运行在 8000 端口)
uvicorn main:app --reload

# 终端 2：启动 Celery 队列 (Windows 下推荐使用 eventlet 或 solo 运行池)
# 如果没有安装 eventlet，可以先 pip install eventlet
celery -A celery_app worker -l info -P eventlet

4. 接口测试流转 (通过 Swagger UI)

打开浏览器访问：http://127.0.0.1:8000/docs

1. 查看预制模板：

   • 调用 GET /api/config/presets
   • 你会看到内置的 4 种模板和推荐维度。

2. 配置审核任务：

   • 调用 POST /api/config
   • 请求体示例：

     {
       "task_name": "task_customer_service_01",
       "prompt_template": "你是一个严格的客服质检专家。请评估以下回复是否解决了用户问题，语气是否礼貌。",
       "dimensions": ["relevance", "politeness"],
       "ai_model": "gpt-4o-mini"
     }

3. 提交数据触发审核：

   • 调用 POST /api/submit
   • 请求体示例：

     {
       "submission_id": "sub_001",
       "task_name": "task_customer_service_01",
       "annotator_id": "user_9527",
       "data": "亲，商品已经发出去了呢，物流慢我也没办法，你爱等不等吧。"
     }

   • 此时你会看到终端 2 的 Celery 开始工作并调用大模型。

4. 查看审核工作台结果：

   • 稍等几秒后，调用 GET /api/workbench/{submission_id}（输入刚才的 sub_001）
   • 你将看到 AI 返回的结构化打分结果、最终结论以及详细的点评建议。