# Implementation Plan: AI 服务需求文档

**Branch**: `001-ai-service-requirements` | **Date**: 2026-04-10 | **Spec**: [spec.md](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)

```text
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)

```text
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 无违规，此节无需填写。