# 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
```