AI-VideoAssistant/api

AI VideoAssistant Backend

Python 后端 API，配合前端 web/ 模块使用。

快速开始

1. 安装依赖

cd api
pip install -r requirements.txt

2. 初始化数据库

python init_db.py

这会：

• 创建 data/app.db SQLite 数据库
• 初始化默认声音数据

可选参数（按需重建）：

# 仅重建数据库（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. 启动服务

# 开发模式 (热重载)
python -m uvicorn app.main:app --reload --host 0.0.0.0 --port 8100

服务运行在: http://localhost:8100

4. 测试 API

# 健康检查
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/ 目录：

模块	端点	方法	说明
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 启动

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	存储桶名称

---

数据库迁移

开发环境重新创建数据库：

rm -f api/data/app.db
python api/init_db.py

---

测试

安装测试依赖

cd api
pip install pytest pytest-cov -q

运行所有测试

# Windows
run_tests.bat

# 或使用 pytest
pytest tests/ -v

运行特定测试

# 只测试声音 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

测试覆盖率

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)

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