label_ai_service/specs/001-ai-service-requirements/plan.md

Implementation Plan: AI 服务需求文档

Branch: 001-ai-service-requirements | Date: 2026-04-10 | Spec: spec.md
Input: Feature specification from /specs/001-ai-service-requirements/spec.md

参考实现计划（主计划）: docs/superpowers/plans/2026-04-10-ai-service-impl.md
本文件为 speckit 规划框架文档，详细 TDD 任务（17 个步骤含完整代码）见上述主计划。

Summary

实现一个独立部署的 Python FastAPI AI 服务，为知识图谱标注平台提供文本三元组提取、图像四元组提取、视频帧处理、问答对生成和 GLM 微调管理能力。服务通过 RustFS S3 API 读写文件，通过 ZhipuAI GLM API 调用大模型，通过回调接口通知 Java 后端异步任务结果。采用 ABC 适配层（LLMClient / StorageClient）保证可扩展性，FastAPI BackgroundTasks 处理视频长任务，全量 TDD 开发。

Technical Context

Language/Version: Python 3.12.13（conda label 环境）
Primary Dependencies: FastAPI ≥0.111, uvicorn[standard] ≥0.29, pydantic ≥2.7, zhipuai ≥2.1, boto3 ≥1.34, pdfplumber ≥0.11, python-docx ≥1.1, opencv-python-headless ≥4.9, numpy ≥1.26, httpx ≥0.27, python-dotenv ≥1.0, pyyaml ≥6.0
Storage: RustFS（S3 兼容协议，boto3 访问）
Testing: pytest ≥8.0 + pytest-asyncio ≥0.23，所有 service 和 router 均有单元测试
Target Platform: Linux 容器（Docker + Docker Compose）
Project Type: web-service
Performance Goals: 文本提取 <60s；图像提取 <30s；视频任务接受 <1s；健康检查 <1s；QA 生成（≤10条）<90s
Constraints: 视频文件大小上限默认 200MB（可通过 MAX_VIDEO_SIZE_MB 环境变量配置）；不访问数据库；GLM 为云端 API，图片须以 base64 传输；ZhipuAI SDK 同步阻塞，须在线程池中执行
Scale/Scope: 低并发（ADMIN 手动触发），同时不超过 5 个视频任务

Constitution Check

GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.

项目 constitution 为未填充的模板，无项目特定约束规则。以下采用通用工程原则进行评估。

原则	状态	说明
测试优先（TDD）	✅ 通过	实现计划采用红绿重构循环，所有模块先写测试
简单性（YAGNI）	✅ 通过	BackgroundTasks 而非 Celery；无数据库；适配层仅当前实现
可观测性	✅ 通过	JSON 结构化日志，含请求/GLM/视频任务维度
错误分类	✅ 通过	4 种异常类（400/502/503/500），结构化响应
可扩展性	✅ 通过	LLMClient / StorageClient ABC 适配层
配置分层	✅ 通过	config.yaml + .env + 环境变量覆盖

GATE RESULT: ✅ 无违规，可进入 Phase 0。

Project Structure

Documentation (this feature)

specs/001-ai-service-requirements/
├── plan.md              # 本文件 (/speckit.plan 输出)
├── research.md          # Phase 0 输出
├── data-model.md        # Phase 1 输出
├── quickstart.md        # Phase 1 输出
├── contracts/           # Phase 1 输出
│   └── api.md
└── tasks.md             # Phase 2 输出 (/speckit.tasks - 未由本命令创建)

Source Code (repository root)

label_ai_service/
├── app/
│   ├── main.py                    # FastAPI 应用入口，lifespan，/health 端点
│   ├── core/
│   │   ├── config.py              # YAML + .env 分层配置，lru_cache 单例
│   │   ├── logging.py             # JSON 结构化日志，请求日志中间件
│   │   ├── exceptions.py          # 自定义异常 + 全局处理器
│   │   ├── json_utils.py          # GLM 响应 JSON 解析（兼容 Markdown 代码块）
│   │   └── dependencies.py        # FastAPI Depends 工厂函数
│   ├── clients/
│   │   ├── llm/
│   │   │   ├── base.py            # LLMClient ABC（chat / chat_vision）
│   │   │   └── zhipuai_client.py  # ZhipuAI 实现（线程池包装同步 SDK）
│   │   └── storage/
│   │       ├── base.py            # StorageClient ABC（download/upload/presigned/size）
│   │       └── rustfs_client.py   # RustFS S3 兼容实现
│   ├── services/
│   │   ├── text_service.py        # TXT/PDF/DOCX 解析 + 三元组提取
│   │   ├── image_service.py       # 四元组提取 + bbox 裁剪
│   │   ├── video_service.py       # 帧提取 + 视频转文本（BackgroundTask）
│   │   ├── qa_service.py          # 文本/图像问答对生成（图像用 base64）
│   │   └── finetune_service.py    # 微调任务提交与查询
│   ├── routers/
│   │   ├── text.py                # POST /api/v1/text/extract
│   │   ├── image.py               # POST /api/v1/image/extract
│   │   ├── video.py               # POST /api/v1/video/extract-frames, /to-text
│   │   ├── qa.py                  # POST /api/v1/qa/gen-text, /gen-image
│   │   └── finetune.py            # POST /api/v1/finetune/start, GET /status/{id}
│   └── models/
│       ├── text_models.py
│       ├── image_models.py
│       ├── video_models.py
│       ├── qa_models.py
│       └── finetune_models.py
├── tests/
│   ├── conftest.py                # mock_llm, mock_storage fixtures
│   ├── test_config.py
│   ├── test_llm_client.py
│   ├── test_storage_client.py
│   ├── test_text_service.py
│   ├── test_text_router.py
│   ├── test_image_service.py
│   ├── test_image_router.py
│   ├── test_video_service.py
│   ├── test_video_router.py
│   ├── test_qa_service.py
│   ├── test_qa_router.py
│   ├── test_finetune_service.py
│   └── test_finetune_router.py
├── config.yaml
├── .env
├── requirements.txt
├── Dockerfile
└── docker-compose.yml

Structure Decision: 单项目结构（Option 1），分层为 routers → services → clients，测试与源码并列。

Complexity Tracking

Constitution 无违规，此节无需填写。