348 lines
8.3 KiB
Markdown
348 lines
8.3 KiB
Markdown
# AI VideoAssistant Backend
|
||
|
||
Python 后端 API，配合前端 `web/` 模块使用。
|
||
|
||
## 快速开始
|
||
|
||
### 1. 安装依赖
|
||
|
||
```bash
|
||
cd api
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
### 2. 初始化数据库
|
||
|
||
```bash
|
||
python init_db.py
|
||
```
|
||
|
||
这会：
|
||
- 创建 `data/app.db` SQLite 数据库
|
||
- 初始化默认声音数据
|
||
|
||
可选参数（按需重建）：
|
||
|
||
```bash
|
||
# 仅重建数据库（drop + create）并初始化默认数据
|
||
python init_db.py --rebuild-db
|
||
|
||
# 仅重建向量库集合（不动 DB 表结构）；会重置文档索引状态为 pending
|
||
python init_db.py --rebuild-vector-store
|
||
|
||
# 同时重建 DB 和向量库
|
||
python init_db.py --rebuild-db --rebuild-vector-store
|
||
|
||
# 仅执行重建，不写入默认数据
|
||
python init_db.py --rebuild-db --skip-seed
|
||
```
|
||
|
||
### 3. 启动服务
|
||
|
||
```bash
|
||
# 开发模式 (热重载)
|
||
python -m uvicorn app.main:app --reload --host 0.0.0.0 --port 8100
|
||
```
|
||
|
||
服务运行在: http://localhost:8100
|
||
|
||
### 4. 测试 API
|
||
|
||
```bash
|
||
# 健康检查
|
||
curl http://localhost:8100/health
|
||
|
||
# 获取助手列表
|
||
curl http://localhost:8100/api/assistants
|
||
|
||
# 获取声音列表
|
||
curl http://localhost:8100/api/voices
|
||
|
||
# 获取通话历史
|
||
curl http://localhost:8100/api/history
|
||
```
|
||
|
||
---
|
||
|
||
## API 文档
|
||
|
||
完整 API 文档位于 [docs/](docs/) 目录：
|
||
|
||
| 模块 | 端点 | 方法 | 说明 |
|
||
|------|------|------|------|
|
||
| **Assistant** | `/api/assistants` | GET | 助手列表 |
|
||
| | | POST | 创建助手 |
|
||
| | `/api/assistants/{id}` | GET | 助手详情 |
|
||
| | | PUT | 更新助手 |
|
||
| | | DELETE | 删除助手 |
|
||
| **Voice** | `/api/voices` | GET | 声音库列表 |
|
||
| | | POST | 添加声音 |
|
||
| | `/api/voices/{id}` | GET | 声音详情 |
|
||
| | | PUT | 更新声音 |
|
||
| | | DELETE | 删除声音 |
|
||
| | `/api/voices/{id}/preview` | POST | 预览声音 |
|
||
| **LLM Models** | `/api/llm` | GET | LLM 模型列表 |
|
||
| | | POST | 添加模型 |
|
||
| | `/api/llm/{id}` | GET | 模型详情 |
|
||
| | | PUT | 更新模型 |
|
||
| | | DELETE | 删除模型 |
|
||
| | `/api/llm/{id}/test` | POST | 测试模型连接 |
|
||
| **ASR Models** | `/api/asr` | GET | ASR 模型列表 |
|
||
| | | POST | 添加模型 |
|
||
| | `/api/asr/{id}` | GET | 模型详情 |
|
||
| | | PUT | 更新模型 |
|
||
| | | DELETE | 删除模型 |
|
||
| | `/api/asr/{id}/test` | POST | 测试识别 |
|
||
| **History** | `/api/history` | GET | 通话历史列表 |
|
||
| | `/api/history/{id}` | GET | 通话详情 |
|
||
| | | PUT | 更新通话记录 |
|
||
| | | DELETE | 删除记录 |
|
||
| | `/api/history/{id}/transcripts` | POST | 添加转写 |
|
||
| | `/api/history/search` | GET | 搜索历史 |
|
||
| | `/api/history/stats` | GET | 统计数据 |
|
||
| **Knowledge** | `/api/knowledge/bases` | GET | 知识库列表 |
|
||
| | | POST | 创建知识库 |
|
||
| | `/api/knowledge/bases/{id}` | GET | 知识库详情 |
|
||
| | | PUT | 更新知识库 |
|
||
| | | DELETE | 删除知识库 |
|
||
| | `/api/knowledge/bases/{kb_id}/documents` | POST | 上传文档 |
|
||
| | `/api/knowledge/bases/{kb_id}/documents/{doc_id}` | DELETE | 删除文档 |
|
||
| | `/api/knowledge/bases/{kb_id}/documents/{doc_id}/index` | POST | 索引文档 |
|
||
| | `/api/knowledge/search` | POST | 知识搜索 |
|
||
| **Workflow** | `/api/workflows` | GET | 工作流列表 |
|
||
| | | POST | 创建工作流 |
|
||
| | `/api/workflows/{id}` | GET | 工作流详情 |
|
||
| | | PUT | 更新工作流 |
|
||
| | | DELETE | 删除工作流 |
|
||
|
||
---
|
||
|
||
## 数据模型
|
||
|
||
### Assistant (小助手)
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| id | string | 助手 ID |
|
||
| name | string | 助手名称 |
|
||
| opener | string | 开场白 |
|
||
| prompt | string | 系统提示词 |
|
||
| knowledgeBaseId | string | 关联知识库 ID |
|
||
| language | string | 语言: zh/en |
|
||
| voice | string | 声音 ID |
|
||
| speed | float | 语速 (0.5-2.0) |
|
||
| hotwords | array | 热词列表 |
|
||
| tools | array | 启用的工具列表 |
|
||
| llmModelId | string | LLM 模型 ID |
|
||
| asrModelId | string | ASR 模型 ID |
|
||
| embeddingModelId | string | Embedding 模型 ID |
|
||
| rerankModelId | string | Rerank 模型 ID |
|
||
|
||
### Voice (声音资源)
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| id | string | 声音 ID |
|
||
| name | string | 声音名称 |
|
||
| vendor | string | 厂商: Ali/Volcano/Minimax |
|
||
| gender | string | 性别: Male/Female |
|
||
| language | string | 语言: zh/en |
|
||
| model | string | 厂商模型标识 |
|
||
| voice_key | string | 厂商 voice_key |
|
||
| speed | float | 语速 |
|
||
| gain | int | 增益 (dB) |
|
||
| pitch | int | 音调 |
|
||
|
||
### LLMModel (模型接入)
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| id | string | 模型 ID |
|
||
| name | string | 模型名称 |
|
||
| vendor | string | 厂商 |
|
||
| type | string | 类型: text/embedding/rerank |
|
||
| base_url | string | API 地址 |
|
||
| api_key | string | API 密钥 |
|
||
| model_name | string | 模型名称 |
|
||
| temperature | float | 温度参数 |
|
||
|
||
### ASRModel (语音识别)
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| id | string | 模型 ID |
|
||
| name | string | 模型名称 |
|
||
| vendor | string | 厂商 |
|
||
| language | string | 语言: zh/en/Multi-lingual |
|
||
| base_url | string | API 地址 |
|
||
| api_key | string | API 密钥 |
|
||
| hotwords | array | 热词列表 |
|
||
|
||
### CallRecord (通话记录)
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| id | string | 记录 ID |
|
||
| assistant_id | string | 助手 ID |
|
||
| source | string | 来源: debug/external |
|
||
| status | string | 状态: connected/missed/failed |
|
||
| started_at | string | 开始时间 |
|
||
| duration_seconds | int | 通话时长 |
|
||
| summary | string | 通话摘要 |
|
||
| transcripts | array | 对话转写 |
|
||
|
||
---
|
||
|
||
## 使用 Docker 启动
|
||
|
||
```bash
|
||
cd api
|
||
|
||
# 启动所有服务
|
||
docker-compose up -d
|
||
|
||
# 查看日志
|
||
docker-compose logs -f backend
|
||
```
|
||
|
||
---
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
api/
|
||
├── app/
|
||
│ ├── __init__.py
|
||
│ ├── main.py # FastAPI 入口
|
||
│ ├── db.py # SQLite 连接
|
||
│ ├── models.py # SQLAlchemy 数据模型
|
||
│ ├── schemas.py # Pydantic 模型
|
||
│ ├── storage.py # MinIO 存储
|
||
│ ├── vector_store.py # 向量存储
|
||
│ └── routers/
|
||
│ ├── __init__.py
|
||
│ ├── assistants.py # 助手 API
|
||
│ ├── history.py # 通话记录 API
|
||
│ └── knowledge.py # 知识库 API
|
||
├── data/ # 数据库文件
|
||
├── docs/ # API 文档
|
||
├── requirements.txt
|
||
├── .env
|
||
├── init_db.py
|
||
└── docker-compose.yml
|
||
```
|
||
|
||
---
|
||
|
||
## 环境变量
|
||
|
||
| 变量 | 默认值 | 说明 |
|
||
|------|--------|------|
|
||
| `PORT` | `8100` | 服务端口 |
|
||
| `DATABASE_URL` | `sqlite:///./data/app.db` | 数据库连接 |
|
||
| `MINIO_ENDPOINT` | `localhost:9000` | MinIO 地址 |
|
||
| `MINIO_ACCESS_KEY` | `admin` | MinIO 密钥 |
|
||
| `MINIO_SECRET_KEY` | `password123` | MinIO 密码 |
|
||
| `MINIO_BUCKET` | `ai-audio` | 存储桶名称 |
|
||
|
||
---
|
||
|
||
## 数据库迁移
|
||
|
||
开发环境重新创建数据库：
|
||
|
||
```bash
|
||
rm -f api/data/app.db
|
||
python api/init_db.py
|
||
```
|
||
|
||
---
|
||
|
||
## 测试
|
||
|
||
### 安装测试依赖
|
||
|
||
```bash
|
||
cd api
|
||
pip install pytest pytest-cov -q
|
||
```
|
||
|
||
### 运行所有测试
|
||
|
||
```bash
|
||
# Windows
|
||
run_tests.bat
|
||
|
||
# 或使用 pytest
|
||
pytest tests/ -v
|
||
```
|
||
|
||
### 运行特定测试
|
||
|
||
```bash
|
||
# 只测试声音 API
|
||
pytest tests/test_voices.py -v
|
||
|
||
# 只测试助手 API
|
||
pytest tests/test_assistants.py -v
|
||
|
||
# 只测试历史记录 API
|
||
pytest tests/test_history.py -v
|
||
|
||
# 只测试知识库 API
|
||
pytest tests/test_knowledge.py -v
|
||
```
|
||
|
||
### 测试覆盖率
|
||
|
||
```bash
|
||
pytest tests/ --cov=app --cov-report=html
|
||
# 查看报告: open htmlcov/index.html
|
||
```
|
||
|
||
### 测试目录结构
|
||
|
||
```
|
||
tests/
|
||
├── __init__.py
|
||
├── conftest.py # pytest fixtures
|
||
├── test_voices.py # 声音 API 测试
|
||
├── test_assistants.py # 助手 API 测试
|
||
├── test_history.py # 历史记录 API 测试
|
||
└── test_knowledge.py # 知识库 API 测试
|
||
```
|
||
|
||
### 测试用例统计
|
||
|
||
| 模块 | 测试用例数 |
|
||
|------|-----------|
|
||
| Voice | 13 |
|
||
| Assistant | 14 |
|
||
| History | 18 |
|
||
| Knowledge | 19 |
|
||
| **总计** | **64** |
|
||
|
||
### CI/CD 示例 (.github/workflows/test.yml)
|
||
|
||
```yaml
|
||
name: Tests
|
||
|
||
on: [push, pull_request]
|
||
|
||
jobs:
|
||
test:
|
||
runs-on: ubuntu-latest
|
||
steps:
|
||
- uses: actions/checkout@v4
|
||
- name: Set up Python
|
||
uses: actions/setup-python@v5
|
||
with:
|
||
python-version: '3.11'
|
||
- name: Install dependencies
|
||
run: |
|
||
pip install -r api/requirements.txt
|
||
pip install pytest pytest-cov
|
||
- name: Run tests
|
||
run: pytest api/tests/ -v --cov=app
|
||
```
|