AI-VideoAssistant/docs/content/concepts/assistants/configuration.md

配置选项

助手配置界面包含多个标签页，每个标签页负责不同方面的配置。

全局设置

全局设置定义助手的核心对话能力。

配置项	说明	建议值
助手名称	用于标识和管理	简洁明确
系统提示词	定义角色、任务和约束	详见提示词指南
开场白	对话开始时的问候语	简短友好
温度参数	控制回复随机性	0.7（通用）/ 0.3（严谨）
上下文长度	保留的历史消息数	10-20

高级选项

• 首轮模式 - 设置首次对话的触发方式
• 打断检测 - 用户打断时的处理策略
• 超时设置 - 无响应时的处理

语音配置

配置语音识别和语音合成参数。

TTS 语音合成

配置	说明
TTS 引擎	选择语音合成服务（阿里/火山/Minimax）
音色	选择语音风格和性别
语速	语音播放速度（0.5-2.0）
音量	语音输出音量（0-100）
音调	语音音调高低（0.5-2.0）

ASR 语音识别

配置	说明
ASR 引擎	选择语音识别服务
语言	识别语言（中文/英文/多语言）
热词	提高特定词汇识别准确率

工具绑定

配置助手可调用的外部工具。

可用工具类型

工具	说明
搜索工具	网络搜索获取信息
天气查询	查询天气预报
计算器	数学计算
知识库检索	RAG 知识检索
自定义工具	HTTP 回调外部 API

配置步骤

1. 在工具列表中勾选需要的工具
2. 配置工具参数（如有）
3. 测试工具调用是否正常

知识关联

关联 RAG 知识库，让助手能够回答专业领域问题。

配置参数

参数	说明	建议值
知识库	选择要关联的知识库	-
相似度阈值	低于此分数不返回	0.7
返回数量	单次检索返回条数	3
检索策略	混合/向量/关键词	混合

多知识库

支持关联多个知识库，系统会自动合并检索结果。

外部链接

配置第三方服务集成和 Webhook 回调。

Webhook 配置

字段	说明
回调 URL	接收事件的 HTTP 端点
事件类型	订阅的事件（对话开始/结束/工具调用等）
认证方式	API Key / Bearer Token / 无

支持的事件

• conversation.started - 对话开始
• conversation.ended - 对话结束
• tool.called - 工具被调用
• human.transfer - 转人工

配置持久化与运行时覆盖

助手配置分为两层：

1. 数据库持久化配置（基线配置）：通过助手管理 API 保存，后续会话默认读取这一层。
2. 会话级覆盖配置（runtime overrides）：仅对当前 WebSocket 会话生效，不会写回数据库。

哪些配置会存到数据库

以下字段会持久化在 assistants / assistant_opener_audio 等表中（通过创建/更新助手写入）：

类别	典型字段
对话行为	name、prompt、opener、firstTurnMode、generatedOpenerEnabled
输出与打断	voiceOutputEnabled、voice、speed、botCannotBeInterrupted、interruptionSensitivity
工具与知识库	tools、knowledgeBaseId
模型与外部模式	configMode、apiUrl、apiKey、llmModelId、asrModelId、embeddingModelId、rerankModelId
开场音频	openerAudioEnabled 及音频文件状态（ready、durationMs 等）

引擎在连接时通过 assistant_id 从后端读取该助手的 sessionStartMetadata 作为默认运行配置。

哪些配置可以在会话中覆盖

客户端可在 session.start.metadata.overrides 中覆盖以下白名单字段（仅当前会话有效）：

• systemPrompt
• greeting
• firstTurnMode
• generatedOpenerEnabled
• output
• bargeIn
• knowledgeBaseId
• knowledge
• tools
• openerAudio

以下字段不能由客户端覆盖：

• services（模型 provider / apiKey / baseUrl 等）
• assistantId / appId / configVersionId（及下划线变体）
• 包含密钥语义的字段（如 apiKey、token、secret、password、authorization）

覆盖示例（代码）

下面示例展示「数据库基线配置 + 会话 overrides」的最终效果。

// 1) 数据库存储的基线配置（示意）
// GET /api/v1/assistants/asst_demo/config -> sessionStartMetadata
{
  "systemPrompt": "你是电商客服助手，回答要简洁。",
  "greeting": "你好，我是你的客服助手。",
  "firstTurnMode": "bot_first",
  "output": { "mode": "audio" },
  "knowledgeBaseId": "kb_orders",
  "tools": [
    { "type": "function", "function": { "name": "query_order" } }
  ]
}

// 2) 客户端发起会话时的覆盖
{
  "type": "session.start",
  "metadata": {
    "channel": "web",
    "history": { "userId": 1001 },
    "overrides": {
      "greeting": "你好，我来帮你查订单进度。",
      "output": { "mode": "text" },
      "knowledgeBaseId": "kb_vip_orders",
      "tools": [
        { "type": "function", "function": { "name": "query_vip_order" } }
      ]
    }
  }
}

// 3) 引擎合并后的有效配置（示意）
{
  "assistantId": "asst_demo",
  "systemPrompt": "你是电商客服助手，回答要简洁。",
  "greeting": "你好，我来帮你查订单进度。",
  "firstTurnMode": "bot_first",
  "output": { "mode": "text" },
  "knowledgeBaseId": "kb_vip_orders",
  "tools": [
    { "type": "function", "function": { "name": "query_vip_order" } }
  ],
  "channel": "web",
  "history": { "userId": 1001 }
}

合并规则可简化为：

effective = {**db_session_start_metadata, **metadata.overrides}

当 WS_EMIT_CONFIG_RESOLVED=true 时，服务端会返回 config.resolved（公开、安全裁剪后的快照）用于前端调试当前生效配置。

配置导入导出

导出配置

1. 在助手详情页点击 更多
2. 选择 导出配置
3. 下载 JSON 格式的配置文件

导入配置

1. 点击 新建助手
2. 选择 从配置导入
3. 上传配置文件