092f9dbfc5
Generated plan.md, research.md, data-model.md, contracts/api.md, quickstart.md, and CLAUDE.md agent context via /speckit-plan.
121 lines
6.2 KiB
Markdown
121 lines
6.2 KiB
Markdown
# 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 无违规，此节无需填写。
|