092f9dbfc5
Generated plan.md, research.md, data-model.md, contracts/api.md, quickstart.md, and CLAUDE.md agent context via /speckit-plan.
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
|
||
```
|