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

Quickstart: AI 服务开发指南

Branch: 001-ai-service-requirements | Date: 2026-04-10

---

环境准备

# 激活 conda 环境
conda activate label

# 安装依赖（在 label_ai_service 目录下）
pip install -r requirements.txt

---

本地开发启动

# 1. 复制并配置 .env（已提交模板）
# 编辑 .env 填写真实的 ZHIPUAI_API_KEY 和 STORAGE_ENDPOINT

# 2. 启动开发服务器
conda run -n label uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

# 3. 访问 Swagger 文档
# http://localhost:8000/docs

---

运行测试

# 运行全部测试
conda run -n label pytest tests/ -v

# 运行指定模块测试
conda run -n label pytest tests/test_text_service.py -v

# 运行带覆盖率报告
conda run -n label pytest tests/ --cov=app --cov-report=term-missing

---

Docker 部署

# 构建镜像
docker build -t label-ai-service:dev .

# 使用 docker-compose 启动（含 RustFS）
docker-compose up -d

# 查看日志
docker-compose logs -f ai-service

# 健康检查
curl http://localhost:8000/health

---

关键配置说明

视频大小上限调整

无需重建镜像，在 .env 中添加：

MAX_VIDEO_SIZE_MB=500

切换大模型

修改 config.yaml：

models:
  default_text: "glm-4-flash"    # 文本模型
  default_vision: "glm-4v-flash" # 视觉模型

---

开发流程（TDD）

详细的 17 个任务步骤（含完整代码）见主实现计划：
docs/superpowers/plans/2026-04-10-ai-service-impl.md

每个任务的开发步骤：

1. 编写失败测试（pytest ... -v 验证失败）
2. 实现最小代码使测试通过（pytest ... -v 验证通过）
3. Commit

---

目录结构速查

app/
├── main.py          # 入口，/health 端点，路由注册
├── core/            # 配置、日志、异常、工具
├── clients/         # LLM 和 Storage 适配层（ABC + 实现）
├── services/        # 业务逻辑（text/image/video/qa/finetune）
├── routers/         # HTTP 路由处理
└── models/          # Pydantic 请求/响应 Schema