企业官网建设流程全解析

mod_llm_robot

FreeSWITCH 语音大模型机器人模块。通过兼容 OpenAI Chat Completions 接口的 LLM 服务，在 FreeSWITCH 会话内完成多轮语音对话、话术打断、静音兜底、关键词挂机、模型工具调用和通话记录回传。

模块注册的拨号计划应用：

<actionapplication="llm_robot"data="<robot_id>"/>

robot_id对应llm_robot.conf中<robot id="...">的id属性（无id属性时兼容回退name属性）。

功能概览

架构总览

┌─────────────────────────────────┐ │ Dialplan │ │ llm_robot(robot_id) │ └──────────────┬──────────────────┘ │ ┌──────────────▼──────────────────┐ │ mod_llm_robot.cpp │ │ (模块入口 / application) │ └──────────────┬──────────────────┘ │ ┌──────────────▼──────────────────┐ │ LLMRobotManager │ │ (全局管理器 / 单例) │ │ ┌──────────────────────────┐ │ │ │ 本地配置 JSON 快照 │ │ │ │ 运行实例索引 (by UUID) │ │ │ │ 共享事件线程池 │ │ │ └──────────────────────────┘ │ └──────────────┬──────────────────┘ │ 每次调用创建 ┌──────────────▼──────────────────┐ │ LLMRobot (单呼叫实例) │ │ ┌──────────────────────────┐ │ │ │ ASR 事件 / LLM 调用 │ │ │ │ TTS 播放 / 工具执行 │ │ │ │ 状态机 / 对话历史 │ │ │ │ KeepAliveHttpClient │ │ │ └──────────────────────────┘ │ └──┬────────┬────────┬────────────┘ │ │ │ ┌──────────────▼──┐ ┌───▼─────┐ ┌▼──────────────┐ │ FreeSWITCH ASR │ │ LLM API │ │ FreeSWITCH │ │ (语音识别) │ │(Chat │ │ TTS/播放 │ │ │ │Complet.)│ │ │ └─────────────────┘ └─────────┘ └───────────────┘

模块内分层

核心设计原理

配置与运行实例分离

LLMRobotManager不缓存可运行的机器人原型对象。模块加载时只把<robot>节点的原始 JSON 保存到_local_robot_configs；application 每次调用都复制 JSON 文本，创建新的LLMRobot并执行DeSerialize()。Session、Channel、对话历史、Token 统计和播放状态都属于本次通话实例。

_running_robots只用于按呼叫 UUID 索引正在运行的实例，供 FreeSWITCH 调度任务和事件回调定位对象。它不是配置缓存，实例在通话停止时删除。

事件所有权与异步分发

播放回调收到的 FreeSWITCH 事件只在回调期间有效。模块先通过switch_event_dup()复制事件，再由LLMRobotEvent（RAII）接管switch_event_t*，析构调用switch_event_destroy()。事件进入管理器的共享线程池，避免在媒体回调中直接执行阻塞的 LLM 请求。

每个机器人使用BeginAsyncOperation()/EndAsyncOperation()记录已入队和执行中的任务。退出时先禁止接收新任务，再等待计数归零，之后才允许释放 Session 和 Channel 裸指针。这是模块避免异步回调访问已释放 FreeSWITCH 会话的核心生命周期约束。

状态协调

单呼叫实例用原子变量、互斥锁和条件变量协调以下状态：

PlaybackMutex和PlaybackCv用于避免普通回复、静音提示和用户讲话互相覆盖。

UUID 间接查找

静音和识别超时任务只携带复制后的 UUID，不长期捕获 FreeSWITCH 会话裸指针。任务触发后通过_running_robots重新查找实例，并核对 task id，再进入异步操作计数。旧任务、已取消任务或已退出的呼叫会被丢弃。

LLM 调用

每个ChatApp各自持有一个openai::OpenAI实例（独立 curl session，天然并发安全），base_url/model/api_key/temperature/max_tokens/enable_thinking全部经配置传入。日志只记录目标、状态和响应长度，不记录 API Key 或完整请求体。

当前主对话路径调用同步、非流式 Chat Completions。SpeakStart/Feed/End/Wait和 HTTP 流式回调能力已存在，但尚未接入ThinkReply()主回复链路。

呼叫流程

Dialplan mod_llm_robot LLMRobotManager LLMRobot FreeSWITCH ASR/TTS Event Pool LLM API │ │ │ │ │ │ │ │── llm_robot(id) ──────>│ │ │ │ │ │ │ │── GetConfig(id) ────>│ │ │ │ │ │ │<── local JSON ───────│ │ │ │ │ │ │── DeserializeRobot ──────────────────────>│ │ │ │ │ │ │── register UUID ──>│ │ │ │ │ │ │── Start ──────────>│ │ │ │ │ │ │ │── start ASR + welcome >│ │ │ │ │ │ │ │── speech event ───>│ │ │ │ │ │<── OnEvent ───────────│<── copy+enqueue ──│ │ │ │ │ │── LLM call ──────────────────────────────────────────────────>│ │ │ │ │<── reply text ────────────────────────────────────────────────│ │ │ │ │── TTS/playback ──────>│ │ │ │ │ │ │ │ │ │ │ │ │ │── stop timers + ASR ─>│ │ │ │ │ │── wait async ops ──>│ │ │ │ │ │ │ │── set chat_message__ ─>│ │ │ │ │ │── remove UUID ────>│ │ │ │

ASR 事件处理

当ReplyBusy为真时，新识别文本追加到历史，但不会并行发起第二个 LLM 请求。

播放、打断与静音

• 播放内容以http://或https://开头时调用switch_ivr_play_file()。
• 其他内容先 URL 解码和 inja 渲染，再调用switch_ivr_speak_text()。
• 模板上下文包含caller和callee，并注册了get()、post()和递归render()回调。
• is_break=true时，用户说话会中断普通播放；静音提示始终允许被打断。
• 每次有效识别重置静音计数。连续静音先轮播silences，达到max_silence_count后播放goodbye并挂机。
• detect_timeout是整通识别阶段的总超时，不因单次成功识别而重新计时。

配置加载

模块使用的 FreeSWITCH 配置名称是llm_robot.conf。仓库内的llm_robot.conf.xml是静态配置示例；实际运行环境也可以由 XML 绑定模块动态返回配置。

加载和调用分为三个阶段：

1. 模块加载：仅解析全局settings（如threads），不缓存任何机器人条目。
2. application 调用：按robot_id现读本地llm_robot.conf中的<robot id="...">JSON 原文（兼容回退name属性），命中后立即创建新对象并反序列化；修改本地静态配置后无需重载模块即可生效。
3. 动态 XML 回退：本地未命中时，把Robot-Id和通道变量放入SWITCH_EVENT_REQUEST_PARAMS请求 XML registry；返回的 JSON 只用于本次调用，同样不缓存。

mod_xml_local已实现llm_robot.conf的动态处理器。本地与动态配置均按需现读，模块内不保留机器人配置快照。

全局设置

机器人字段

工具调用

每个tools元素包含：

工具必须同时存在于机器人配置和本地ToolFunctions白名单中才能执行：

transfer.arguments.to应由服务端配置固定，避免模型改写目标号码。请求设置parallel_tool_calls=false，同时兼容tool_calls和function_call响应。配置其他名称的工具只暴露给模型，执行阶段被白名单拒绝。

聊天记录输出

模块维护两套数据：

• ChatHistory：发给模型的有限上下文，仅保留 user/assistant 文本。
• ChatMessages：通话审计记录，保存全部已识别用户文本和实际播放文本。

退出时ChatMessages序列化为 JSON 数组写入chat_message__：

该变量可能包含客户对话内容，后续消费按敏感业务数据处理。

停止与卸载顺序

单通呼叫结束时，管理器执行：

1. 标记实例为停止，取消静音和识别超时任务。
2. 从_running_robots删除 UUID，阻止后续调度任务获得实例。
3. 禁止新异步任务并等待现有任务完成。
4. 把聊天记录写入仍然有效的 FreeSWITCH channel。
5. 返回 application，让 FreeSWITCH 会话线程继续释放资源。

模块卸载时先阻止新分发，清理本地配置快照，停止全部运行实例，等待异步任务完成，再销毁线程池。必须保持"停止生产 → 等待消费 → 释放资源"的顺序。

依赖与构建

按照仓库规范，只能从/root/fs使用统一脚本编译：

./fs.sh compile freeswitch

编译成功不等于镜像已发布、打标签或服务已重启，这些步骤需要分别授权。

开发检查清单

修改本模块时至少确认：

1. 配置字段是否同时更新了反序列化、默认值/范围和本文档。
2. 新事件是否复制或明确转移了switch_event_t所有权。
3. 新异步任务是否进入BeginAsyncOperation()/EndAsyncOperation()计数。
4. 调度任务是否通过 UUID 查找实例并校验 task id。
5. 停止流程是否拒绝新任务、等待旧任务，并最终释放机器人实例。
6. 播放、用户讲话、静音提示和 LLM 回复是否可能互相覆盖或死锁。
7. 工具固定参数是否覆盖模型参数，终止工具是否正确停止机器人。
8. 日志是否包含 UUID 和底层错误，同时避免请求体、凭据及客户隐私泄漏。
9. 通话退出前是否等待异步操作完成并成功写入chat_message__。
10. 使用git diff --check做静态检查；只有得到明确授权后才执行仓库编译脚本。

这篇文章把 AI 外呼的链路和落地要点讲清楚了。mod_llm_robot 这个开源模块的完整源码我已开源，可以在下面的仓库获取：

• GitHub：https://github.com/pzhu1015/sales
• Gitee（国内访问更快）：https://gitee.com/pzhu1015/sales

如果你正在做或打算做智能外呼 / 呼叫中心，除了这个模块，还有 FreeSWITCH 部署、ASR/TTS 对接、Kamailio 负载、录音上云等相关方案，欢迎到仓库交流和看更多实现。

欢迎技术交流，一起把 AI 外呼做好。

本文为技术经验分享，欢迎收藏转发。