110 lines
2.1 KiB
Markdown
110 lines
2.1 KiB
Markdown
|
# Quickstart: AI 服务开发指南
|
|||
|
|
|
|||
|
|
**Branch**: `001-ai-service-requirements` | **Date**: 2026-04-10
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 环境准备
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
# 激活 conda 环境
|
|||
|
|
conda activate label
|
|||
|
|
|
|||
|
|
# 安装依赖（在 label_ai_service 目录下）
|
|||
|
|
pip install -r requirements.txt
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 本地开发启动
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
# 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
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 运行测试
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
# 运行全部测试
|
|||
|
|
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 部署
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
# 构建镜像
|
|||
|
|
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` 中添加：
|
|||
|
|
```ini
|
|||
|
|
MAX_VIDEO_SIZE_MB=500
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 切换大模型
|
|||
|
|
|
|||
|
|
修改 `config.yaml`：
|
|||
|
|
```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
|
|||
|
|
```
|