1. 项目概述当FreeSWITCH遇上ChatGPT我们能做什么最近在折腾一个挺有意思的项目我把它命名为“laoyin/freeswitch_chatGPT”。简单来说这是一个将FreeSWITCH这个强大的开源软交换平台与ChatGPT这类大语言模型的智能对话能力进行深度融合的尝试。如果你对VoIP网络电话、呼叫中心自动化或者智能语音交互感兴趣那么这个项目背后的思路和实现细节或许能给你带来一些启发。FreeSWITCH是什么它是一个功能极其丰富的通信引擎可以处理语音、视频、文本等各种实时通信协议。我们平时接触到的电话系统、视频会议、呼叫中心很多底层都是基于它构建的。而ChatGPT的能力大家都很熟悉了它能理解自然语言进行流畅的对话甚至完成一些简单的任务。那么把这两者结合起来想象空间就很大了一个能“听懂”人话、并“说出”人话的智能电话系统。这个项目的核心目标就是让FreeSWITCH具备调用ChatGPT API的能力。这样一来任何打入FreeSWITCH的电话都可以被转交给ChatGPT来处理。比如你可以搭建一个7x24小时在线的智能客服自动接听客户咨询可以做一个智能语音助手通过电话帮你查天气、定闹钟甚至可以做一个有趣的互动语音游戏。关键在于这一切的“大脑”是ChatGPT它的对话自然度和问题解决能力远超市面上大多数基于固定关键词匹配的IVR交互式语音应答系统。2. 核心架构与设计思路拆解2.1 为什么选择FreeSWITCH ChatGPT的组合在通信领域实现语音交互通常有两条主流路径。一条是“云服务全家桶”比如直接使用某云厂商提供的语音识别、自然语言处理和语音合成的串联服务。这条路径开发快但定制性差、成本高且数据流经第三方。另一条是“自建核心外接智能”这正是本项目选择的路径。FreeSWITCH在这里扮演了“通信中枢”和“协议转换器”的角色。它的强大之处在于协议无关性无论是传统的PSTN电话、SIP协议还是WebRTCFreeSWITCH都能无缝接入这保证了我们的智能电话可以触达几乎所有终端。强大的媒体处理能力它内置了录音、放音、会议、编解码转换等功能为我们处理语音流提供了坚实基础。可编程性Mod_事件套接字这是关键。FreeSWITCH可以通过一个TCP Socket向外发送所有系统事件如电话呼入、挂断并接收外部指令如播放文件、录音、转接。这让我们可以用任何编程语言如Python、Node.js写一个外部程序来“控制”FreeSWITCH实现复杂逻辑。而ChatGPT则作为“对话智能体”。我们不需要自己训练一个复杂的NLP模型直接通过OpenAI的API就能获得顶尖的对话能力。我们的架构本质上就是让FreeSWITCH把用户的语音转换成文本送给ChatGPT再把ChatGPT返回的文本转换成语音播放给用户。2.2 整体数据流与组件设计整个系统的运行流程可以拆解为以下几个核心步骤我画了一个简单的逻辑图在脑子里你可以跟着这个思路来理解呼入与接听用户拨打号码FreeSWITCH接起电话。语音转文本STTFreeSWITCH开始录音并将录音流或录音文件发送给一个语音识别服务转换成文字。智能对话LLM将识别出的文字连同一些对话历史上下文通过API发送给ChatGPT。文本转语音TTS将ChatGPT返回的文字回复通过一个语音合成服务转换成音频文件如WAV或MP3。播放与循环FreeSWITCH将合成的音频文件播放给用户。然后回到第2步形成交互循环直到用户挂机。因此除了FreeSWITCH本身我们还需要三个外部服务/模块STT服务用于语音识别。可以选择开源方案如Vosk离线、轻量或云服务如Google Cloud Speech-to-Text、Azure Speech Services更准、需网络。LLM服务即ChatGPT API这是核心。TTS服务用于语音合成。同样有开源选择如eSpeak、Piper或云服务如Azure TTS、Google TTS。我们的控制程序比如一个Python脚本将作为“胶水”和“大脑”通过FreeSWITCH的mod_event_socket接口与FS通信同时协调调用STT、ChatGPT、TTS这三个服务。设计取舍心得这里有一个关键决策点语音流处理放在哪里一种方案是让FreeSWITCH实时将音频流推送给我们的控制程序由程序调用STT。这更实时但对程序性能和网络要求高。另一种更简单稳定的方案是让FreeSWITCH先录一小段音比如用户说完一句话生成一个临时文件再由控制程序读取这个文件去识别。本项目初期建议采用后者文件方式稳定性优先。3. 环境准备与核心组件配置3.1 FreeSWITCH的安装与基础配置首先你需要一个运行中的FreeSWITCH。可以从源码编译也可以使用预编译的包。这里以Ubuntu系统为例简述安装和关键配置# 添加FreeSWITCH仓库并安装 sudo apt update sudo apt install -y gnupg2 wget lsb-release wget -O - https://files.freeswitch.org/repo/deb/debian-release/fsstretch-archive-keyring.asc | sudo apt-key add - echo deb http://files.freeswitch.org/repo/deb/debian-release/ lsb_release -sc main | sudo tee /etc/apt/sources.list.d/freeswitch.list sudo apt update sudo apt install -y freeswitch-meta-all安装后最重要的配置是启用mod_event_socket这是外部程序控制FS的通道。编辑/etc/freeswitch/autoload_configs/event_socket.conf.xmlconfiguration nameevent_socket.conf descriptionSocket Client settings !-- 监听在本机所有IP的8021端口 -- param namelisten-ip value0.0.0.0/ param namelisten-port value8021/ !-- 设置一个密码你的控制程序需要用它连接 -- param namepassword valueClueCon/ !-- 允许本机连接 -- param nameapply-inbound-acl valueloopback.auto/ /settings /configuration修改后重启FreeSWITCHsudo systemctl restart freeswitch。你可以用fs_cli命令连接上去测试密码是ClueCon。3.2 外部控制程序的选择与依赖安装控制程序是项目的“大脑”。Python因其丰富的库和易用性是绝佳选择。我们需要安装几个关键库pip install ESL # FreeSWITCH的Event Socket库用于连接和控制FS pip install openai # 调用ChatGPT API # 根据你选择的STT/TTS服务安装相应的SDK例如 # pip install azure-cognitiveservices-speech # 如果使用Azure语音服务 # pip install vosk # 如果使用开源Vosk这里重点说下ESL库。它是FreeSWITCH官方提供的Python绑定允许你连接Event Socket端口发送命令和接收事件。一个最简单的连接示例import ESL connection ESL.ESLconnection(localhost, 8021, ClueCon) if connection.connected(): print(Connected to FreeSWITCH!) # 可以发送命令如response connection.api(status) else: print(Connection failed!)3.3 ChatGPT API与语音服务的准备OpenAI API去OpenAI官网注册获取API Key。建议在代码中通过环境变量读取不要硬编码。export OPENAI_API_KEYyour-api-key-here在Python中调用from openai import OpenAI client OpenAI(api_keyos.environ.get(OPENAI_API_KEY)) response client.chat.completions.create( modelgpt-3.5-turbo, messages[{role: user, content: 用户说的话}] ) reply_text response.choices[0].message.content语音服务STT/TTS为简化起步我建议初期使用离线开源方案避免网络延迟和费用问题。STT使用Vosk。它支持多种语言模型小准确度尚可。你需要从Vosk官网下载对应语言的小模型如vosk-model-small-en-us-0.15。TTS使用Piper。这是一个质量很高的开源神经语音合成项目声音比传统的eSpeak自然得多。你需要下载Piper的可执行文件和语音模型。将Vosk和Piper的模型文件放在项目目录下我们的控制程序会直接调用它们。实操心得模型选择Vosk有不同大小的模型small模型适合快速测试和资源有限的环境large模型更准确但更耗资源。Piper的语音模型也有不同风格如en_US-amy-medium是美式女声可以根据喜好选择。初期建议都用small或medium模型确保流程跑通。4. 核心交互逻辑的代码实现4.1 建立事件监听与呼叫处理框架我们的控制程序需要作为一个常驻的“服务”持续监听FreeSWITCH的事件并在有电话呼入时触发处理流程。核心是利用ESL库的事件监听模式。import ESL import threading import logging logging.basicConfig(levellogging.INFO) logger logging.getLogger(__name__) class FreeswitchChatGPTBot: def __init__(self, hostlocalhost, port8021, passwordClueCon): self.con ESL.ESLconnection(host, port, password) if not self.con.connected(): raise ConnectionError(Could not connect to FreeSWITCH) logger.info(Connected to FreeSWITCH Event Socket) # 订阅我们关心的事件CHANNEL_CREATE是通道创建来电 self.con.events(plain, CHANNEL_CREATE CHANNEL_ANSWER CHANNEL_HANGUP) def run(self): 主循环持续监听事件 while True: try: e self.con.recvEvent() if e: event_name e.getHeader(Event-Name) # 当有新的通话通道创建时电话呼入 if event_name CHANNEL_CREATE: # 获取通话的唯一UUID call_uuid e.getHeader(Unique-ID) # 获取主叫号码 caller_id e.getHeader(Caller-Caller-ID-Number) logger.info(fIncoming call from {caller_id}, UUID: {call_uuid}) # 在一个新线程中处理这个通话避免阻塞其他事件 threading.Thread(targetself.handle_call, args(call_uuid,), daemonTrue).start() except Exception as ex: logger.error(fError in event loop: {ex}) break def handle_call(self, uuid): 处理单个通话的核心函数 # 第一步接听电话 self.con.api(fuuid_answer {uuid}) # 第二步播放欢迎语可以直接用TTS生成或播放预录音频 self.play_tts(uuid, Hello, I am your AI assistant. How can I help you today?) # 第三步进入主对话循环 self.dialog_loop(uuid)这个框架建立了一个事件驱动模型。run()方法是一个无限循环监听FS发来的事件。一旦有CHANNEL_CREATE来电事件就提取通话的唯一标识UUID然后启动一个新的线程去专门处理这个通话handle_call。这样就能同时处理多个来电。4.2 实现录音、STT、LLM、TTS的完整链条在dialog_loop方法中我们需要实现“录音-STT-ChatGPT-TTS-播放”这个核心循环。这里以使用VoskSTT和PiperTTS的离线方案为例。import json import subprocess import os from openai import OpenAI from vosk import Model, KaldiRecognizer import wave class FreeswitchChatGPTBot(FreeswitchChatGPTBot): def __init__(self, ...): super().__init__(...) # 初始化OpenAI客户端 self.openai_client OpenAI(api_keyos.getenv(OPENAI_API_KEY)) # 加载Vosk语音识别模型 self.stt_model Model(path./vosk-model-small-en-us-0.15) # Piper TTS路径和模型 self.piper_path ./piper/piper self.tts_model ./piper/voices/en_US-amy-medium.onnx def record_and_transcribe(self, uuid, record_seconds5): 让FreeSWITCH录音并用Vosk识别 # 1. 让FS录音到临时文件 record_path f/tmp/recording_{uuid}.wav # 使用FS的record应用录音。这里录音5秒或检测到静音停止。 self.con.api(fuuid_record {uuid} start {record_path} 300 5) # 假设等待录音完成实际生产环境需要用事件监听录音完成 import time time.sleep(record_seconds) self.con.api(fuuid_record {uuid} stop) # 2. 使用Vosk识别录音文件 if not os.path.exists(record_path): return wf wave.open(record_path, rb) recognizer KaldiRecognizer(self.stt_model, wf.getframerate()) text while True: data wf.readframes(4000) if len(data) 0: break if recognizer.AcceptWaveform(data): result json.loads(recognizer.Result()) text result.get(text, ) result json.loads(recognizer.FinalResult()) text result.get(text, ) wf.close() # 清理临时文件 os.remove(record_path) return text.strip() def get_ai_response(self, user_input, conversation_history): 调用ChatGPT API获取回复 # 构造消息历史保持上下文 messages conversation_history [{role: user, content: user_input}] try: response self.openai_client.chat.completions.create( modelgpt-3.5-turbo, messagesmessages, max_tokens150, temperature0.7 ) return response.choices[0].message.content except Exception as e: logger.error(fOpenAI API error: {e}) return Im sorry, I encountered an error. def text_to_speech_with_piper(self, text, output_path): 使用Piper将文本合成语音文件 # Piper命令示例echo “text” | ./piper --model voice.onnx --output_file output.wav cmd fecho {text} | {self.piper_path} --model {self.tts_model} --output_file {output_path} subprocess.run(cmd, shellTrue, checkTrue) def play_tts(self, uuid, text): 合成并播放语音 tts_path f/tmp/tts_{uuid}.wav self.text_to_speech_with_piper(text, tts_path) # 使用FS的playback应用播放生成的音频文件 self.con.api(fuuid_broadcast {uuid} {tts_path} aleg) os.remove(tts_path) def dialog_loop(self, uuid): 主对话循环 conversation_history [{role: system, content: You are a helpful AI assistant on a phone call. Keep your responses concise and natural for spoken conversation.}] max_turns 10 # 防止无限循环设置最大对话轮次 for turn in range(max_turns): # 1. 播放提示音请用户说话 self.play_tts(uuid, Please speak now.) # 2. 录音并识别 user_speech_text self.record_and_transcribe(uuid) if not user_speech_text: self.play_tts(uuid, I didnt catch that. Could you please repeat?) continue logger.info(fUser said: {user_speech_text}) # 3. 获取AI回复 ai_reply self.get_ai_response(user_speech_text, conversation_history) logger.info(fAI replies: {ai_reply}) # 更新对话历史 conversation_history.append({role: user, content: user_speech_text}) conversation_history.append({role: assistant, content: ai_reply}) # 4. 播放AI回复 self.play_tts(uuid, ai_reply) # 简单判断是否结束如果用户说再见或类似的话 if any(word in user_speech_text.lower() for word in [bye, goodbye, thanks, thank you]): self.play_tts(uuid, Goodbye! Have a great day.) break # 挂断电话 self.con.api(fuuid_kill {uuid})这段代码构成了最核心的交互引擎。dialog_loop控制着对话的轮次。每一轮中提示用户说话 - 录音 - Vosk识别 - 发送文本到ChatGPT - Piper合成回复语音 - 播放。对话历史被维护并发送给ChatGPT使其具备上下文理解能力。关键细节与避坑指南录音控制示例中用了简单的sleep等待录音这不精确。生产环境应监听RECORD_STOP事件或使用play_and_detect_speech应用在检测到静音时自动停止录音。错误处理网络调用OpenAI API和外部进程调用Piper必须包裹在try-except中并给出降级回复如播放“网络出错”的提示音否则一次异常就会导致整个通话线程崩溃。资源清理务必删除临时生成的录音和TTS文件/tmp/recording_*.wav,/tmp/tts_*.wav否则磁盘很快会被占满。并发限制OpenAI API有速率限制Piper合成语音是CPU密集型操作。当并发通话数多时需要引入任务队列和线程池来管理避免资源耗尽。5. 高级功能与优化实践5.1 实现语音活动检测与打断上面的简单实现是“你说完我再说”的回合制体验不自然。更好的体验是允许用户打断AI的说话barge-in。这需要语音活动检测。FreeSWITCH内置了play_and_detect_speech应用它可以在播放音频的同时监听是否有语音输入。我们可以改造play_tts环节def play_tts_with_bargein(self, uuid, text): 播放TTS并允许用户打断 tts_path f/tmp/tts_{uuid}.wav self.text_to_speech_with_piper(text, tts_path) # 使用play_and_detect_speech。参数detect_timeout是等待语音的超时。 # 如果用户在播放过程中说话该应用会停止播放并返回。 bgapi_command fuuid_broadcast {uuid} {tts_path} aleg detect_speech vosk:vosk-model-small-en-us-0.15 default 3000 response self.con.bgapi(bgapi_command) # 解析响应判断是正常播放完毕还是被语音打断 # ... (解析逻辑通常需要监听特定事件如DETECTED_SPEECH)实现完整的打断逻辑比较复杂需要更精细的事件处理。但核心思想是将单纯的播放改为“边播放边监听”。一旦检测到用户语音立即停止播放并开始处理用户的输入。5.2 集成云端语音服务提升体验离线方案部署简单但Vosk和Piper的识别/合成质量与顶尖的云服务仍有差距。如果你想追求更好的用户体验可以替换为Azure或Google的语音服务。以Azure认知服务为例替换STT和TTS部分import azure.cognitiveservices.speech as speechsdk class FreeswitchChatGPTBot(FreeswitchChatGPTBot): def __init__(self, ...): # ... 其他初始化 speech_key os.getenv(AZURE_SPEECH_KEY) service_region eastus self.speech_config speechsdk.SpeechConfig(subscriptionspeech_key, regionservice_region) # 设置语音例如美式英语女声 self.speech_config.speech_synthesis_voice_name en-US-JennyNeural def record_and_transcribe_azure(self, uuid, record_seconds5): 使用Azure语音识别 record_path f/tmp/recording_{uuid}.wav # ... FreeSWITCH录音部分同上 ... audio_config speechsdk.AudioConfig(filenamerecord_path) speech_recognizer speechsdk.SpeechRecognizer(speech_configself.speech_config, audio_configaudio_config) result speech_recognizer.recognize_once() os.remove(record_path) if result.reason speechsdk.ResultReason.RecognizedSpeech: return result.text else: return def text_to_speech_azure(self, text, output_path): 使用Azure语音合成 audio_config speechsdk.AudioConfig(filenameoutput_path) synthesizer speechsdk.SpeechSynthesizer(speech_configself.speech_config, audio_configaudio_config) result synthesizer.speak_text_async(text).get() if result.reason ! speechsdk.ResultReason.SynthesizingAudioCompleted: logger.error(fAzure TTS failed: {result.reason})云端服务的API更稳定识别率和语音自然度也高得多但会产生费用并且依赖网络。你需要根据项目需求质量、成本、延迟、隐私来权衡选择。5.3 对话状态管理与上下文优化目前的对话历史是简单的列表对于长对话或复杂任务可能不够。我们可以引入简单的对话状态管理。例如实现一个“任务导向”的对话。假设是订餐机器人我们需要收集“菜品”、“数量”、“送餐地址”等信息。class ConversationState: def __init__(self, call_uuid): self.uuid call_uuid self.stage greeting # greeting - ask_dish - ask_quantity - ask_address - confirm self.slots {dish: None, quantity: None, address: None} def update_based_on_ai_response(self, ai_reply): 根据AI的回复解析并更新状态简单规则或意图识别 # 这里可以简单使用关键词匹配或集成一个小的意图分类模型 if what dish in ai_reply.lower(): self.stage ask_dish elif how many in ai_reply.lower(): self.stage ask_quantity # ... def get_system_prompt(self): 根据当前状态生成给ChatGPT的系统提示引导对话 base_prompt You are an AI order-taking assistant. You are in a phone call. if self.stage ask_dish: base_prompt You need to ask the customer what dish they would like to order. elif self.stage ask_quantity: base_prompt f The customer wants {self.slots[dish]}. Now ask for the quantity. # ... 其他状态 return base_prompt然后在get_ai_response中将get_system_prompt()返回的内容作为system角色的消息可以更精准地控制AI的对话行为完成多轮信息收集的任务。6. 部署、调试与性能调优6.1 系统部署与进程管理开发完成后我们需要将控制程序部署为系统服务确保它能在后台稳定运行并且开机自启。创建系统服务文件以systemd为例/etc/systemd/system/fschatgpt.service[Unit] DescriptionFreeSWITCH ChatGPT Integration Bot Afternetwork.target freeswitch.service Wantsfreeswitch.service [Service] Typesimple Userfreeswitch # 建议使用freeswitch用户运行权限一致 WorkingDirectory/path/to/your/project EnvironmentOPENAI_API_KEYyour_key EnvironmentAZURE_SPEECH_KEYyour_azure_key ExecStart/usr/bin/python3 /path/to/your/project/bot_main.py Restartalways RestartSec10 [Install] WantedBymulti-user.target启用并启动服务sudo systemctl daemon-reload sudo systemctl enable fschatgpt.service sudo systemctl start fschatgpt.service # 查看日志 sudo journalctl -u fschatgpt.service -f6.2 日志记录与问题排查健全的日志是调试的命脉。除了Python的logging模块我们还应该记录FreeSWITCH的详细日志。FreeSWITCH日志编辑/etc/freeswitch/autoload_configs/console.conf.xml和logfile.conf.xml将日志级别调到DEBUG生产环境调回INFO或WARNING。param namelog-level valuedebug/查看FS日志tail -f /usr/local/freeswitch/log/freeswitch.log控制程序日志使用logging模块输出到文件并合理设置级别。logging.basicConfig( levellogging.DEBUG, format%(asctime)s - %(name)s - %(levelname)s - %(message)s, handlers[ logging.FileHandler(/var/log/fschatgpt.log), logging.StreamHandler() ] )当通话出现问题时按照以下顺序排查检查服务状态systemctl status fschatgpt freeswitch。查看控制程序日志看是否有Python异常抛出。查看FreeSWITCH日志搜索对应的通话UUID看事件流是否正常CHANNEL_CREATE,CHANNEL_ANSWER,PLAYBACK_START,RECORD_STOP等。检查临时文件查看/tmp/目录下是否生成了recording_*.wav和tts_*.wav文件并尝试手动播放确认录音和TTS是否正常工作。网络与API检查是否能访问OpenAI API和云端语音服务如果使用了。6.3 性能瓶颈分析与优化建议随着并发量上升系统可能会遇到瓶颈。以下是一些常见的性能点和优化思路组件潜在瓶颈优化建议FreeSWITCH媒体处理编解码、录音消耗CPU。使用更高效的音频编码如OPUS调整录音参数采样率、静音检测阈值。控制程序 (Python)全局解释器锁GIL限制多线程CPU性能HTTP API调用阻塞。对于计算密集型任务如Vosk识别使用multiprocessing进程池。对于I/O密集型任务网络请求使用asyncio异步框架。STT/TTS (离线)Vosk/Piper模型推理消耗CPU/内存。单个模型处理慢。为Piper TTS启用--cuda如果有GPU。部署多个TTS工作进程通过队列分发任务。考虑使用更轻量的模型。STT/TTS (云端)网络延迟和API调用速率限制。实现请求队列和限流器。使用长连接或流式识别/合成如果API支持以减少延迟。配置合理的重试和超时机制。ChatGPT APIToken消耗成本、响应延迟、速率限制。使用gpt-3.5-turbo而非gpt-4以降低成本和提高速度。在系统提示中明确要求回复简洁。实现对话摘要功能将长上下文压缩后再发送节省Token。一个重要的优化是引入消息队列如Redis或RabbitMQ。主事件监听线程只负责接收FS事件并将任务如“处理UUID为XXX的语音”放入队列。然后由一组工作进程/线程从队列中取出任务执行。这样可以解耦平滑流量高峰并方便水平扩展。7. 安全考量与生产环境建议将这样一个系统暴露在公网安全至关重要。FreeSWITCH安全修改默认密码立即修改event_socket.conf.xml中的默认密码ClueCon。配置ACL在event_socket.conf.xml中apply-inbound-acl不要设置为any而是只允许控制程序所在服务器的IP。SIP安全如果从公网接SIP电话务必配置acl.conf.xml和sofia.conf.xml使用强密码考虑启用TLS加密。定期更新保持FreeSWITCH版本更新修复已知漏洞。API密钥管理绝不硬编码OpenAI、Azure等API密钥必须通过环境变量或安全的密钥管理服务如HashiCorp Vault传入。最小权限原则在云服务商处为应用创建仅有必要权限的服务账号或API密钥。数据隐私录音文件临时录音文件在处理后应立即删除代码中已做。如果因合规需要保留必须加密存储并设置访问权限。对话内容发送给ChatGPT的对话内容可能包含用户隐私。应在系统提示中明确要求AI不存储或滥用数据。对于高敏感场景可以考虑使用本地部署的大模型如通过Ollama部署Llama 2来避免数据出域。监控与告警监控控制程序和FreeSWITCH的进程状态、CPU/内存使用率。监控API调用错误率、延迟和费用。设置告警当服务异常或错误率超过阈值时通过邮件、短信等方式通知。这个项目从技术验证到生产就绪中间还有很长的路要走。但它的核心架构——利用FreeSWITCH的灵活性和ChatGPT的智能——为我们打开了一扇门通往智能语音交互的广阔天地。无论是做一个玩具还是一个严肃的商业应用希望这份详细的拆解能成为你脚下坚实的一块砖。