概述

智能语音交互服务，完整流程：

  1. 接收用户语音输入：MP3格式音频（16kHz/单声道）
  2. 语音识别转文本（ASR）：通过ASR服务将音频转为文本
  3. 结合RAG增强生成回复：使用检索增强生成（Retrieval-Augmented Generation）技术，基于本地知识库生成响应
  4. 文本转语音（TTS）：将生成的文本转为语音，支持自定义音色（通过reference_id指定）
  5. 返回语音文件路径：用户可通过返回的URL直接访问生成的语音文件

快速开始

1
2
3
4
# 示例请求（需替换API密钥和文件路径）
curl -X POST "http://localhost:8000/dialogue_tts/" \
     -H "X-API-Key: your_api_key" \
     -F "mp3_file=@user_audio.mp3"

接口文档

1. 语音对话处理

  • URL: /dialogue_tts/
  • 方法: POST
  • 认证: X-API-Key 请求头
  • 参数:
    • mp3_file (File): 用户上传的MP3文件，要求 16kHz采样率、单声道，文件大小不超过10MB
    • reference_id (可选): TTS音色参考ID，默认为config.yml中配置的默认音色
  • 响应示例:
    1
    2
    3
    {
      "file_path": "/static/output_1a2b3c4d.mp3"
    }

2. 文件清理

  • URL: /clean_file/{filename}
  • 方法: DELETE
  • 参数:
    • filename (路径参数): 需清理的文件名（如output_1a2b3c4d.mp3）
  • 限制: 仅允许清理static/和RAG/documents/目录下的文件

3. 上传知识文档

  • URL: /upload_RAG/
  • 方法: POST
  • 限制:
    • 仅支持.txt文件，UTF-8编码
    • 单个文件大小不超过5MB
  • 功能: 上传文档至RAG/documents/目录，实时更新知识库

4. 列出RAG文档

  • URL: /list_RAG
  • 方法: GET
  • 响应示例:
    1
    2
    3
    {
      "files": ["doc1.txt", "doc2.txt"]
    }

认证方式

所有接口需在请求头中添加 X-API-Key，密钥配置于 config.yml 的 app.call_parameters.api_key：

1
headers = {"X-API-Key": "your_api_key"}

错误码

状态码 说明 可能原因
401 无效API密钥 请求头未携带或密钥错误
400 无效请求/文件类型错误 上传非MP3文件或空文件
403 非法文件路径 尝试清理非授权目录下的文件
404 文件不存在 清理或访问的文件不存在
500 内部错误 ASR/TTS服务异常或LLM响应失败
503 服务不可用 依赖服务不可用

技术细节

RAG配置

  • 向量数据库: Qdrant（本地持久化存储，路径为RAG/qdrant/）
  • 检索策略: 相似度Top 5，基于文本嵌入模型text-embedding-v1
  • 知识库管理: 文档需上传至RAG/documents/，仅支持.txt格式

语音参数

服务 采样率 声道 其他要求
ASR 16kHz 单声道 比特率≥128kbps
TTS 24kHz 单声道 输出格式为MP3，带ID3标签

部署指南

  1. 目录结构：

    1
    2
    3
    4
    5
    6
    ├── config.yml            # 配置文件
    ├── static/               # 临时文件存储（自动清理）
    ├── RAG/
    │   ├── documents/        # RAG知识库文档
    │   └── qdrant/           # Qdrant向量数据库数据
    ├── logs/                 # 日志文件（按日滚动）

  2. 配置文件示例（config.yml）：

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    app:
      call_parameters:
        api_key: "your_call_key"  # 通过环境变量 APP_CALL_PARAMETERS_API_KEY 可覆盖
      aliyun:
        api_key: "aliyun_key"     # 通过环境变量 APP_ALIYUN_API_KEY 可覆盖
        base_url: "https://dashscope.aliyuncs.com/api/v1"
        chat_model: "qwen-max"    # 对话模型
        emb_model: "text-embedding-v1"  # 嵌入模型
      fish_audio:
        api_key: "fish_key"       # 通过环境变量 APP_FISH_AUDIO_API_KEY 可覆盖
        default_reference_id: "default_voice"  # 默认音色ID

  3. 启动命令：

    1
    2
    # 启动服务（支持环境变量覆盖配置）
    python index.py

依赖列表（requirements.txt）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
fastapi>=0.68.0
uvicorn>=0.15.0
openai>=1.0.0
llama-index-core>=0.10.0
llama-index-llms-openai>=0.1.0
llama-index-embeddings-openai>=0.1.0
llama-index-vector-stores-qdrant>=0.1.0
qdrant-client>=1.6.0
pygame>=2.0.1
aiofiles>=0.7.0
python-multipart>=0.0.5
pyyaml>=6.0
chardet>=4.0.0
fish-audio-sdk>=0.1.0