亢 · AIRTC-CSDN博客

原创第12章 RAG 流程与原理详解

本文详解RAG（检索增强生成）原理与流程：通过向量化将文本转为数字，利用语义相似则向量相近的特性，实现精准检索；系统分写入（离线）与查询（在线）两条路径，强调两者必须使用同一向量化模型以避免失效；输入由人设约束、检索资料与用户问题三部分构成，确保回答准确且不编造；对比显示，加RAG后回答基于真实业务数据，可动态更新而无需重训模型。适用于需对接企业知识的语音智能体，是提升问答准确率的核心技术。

2026-09-15 16:22:46 32

本文摘自《VoiceAgent 全栈实战》原理篇，作者，清华社签约作者。一段声音从用户嘴边出发，最终回到用户耳边，中间换了好几种形态：空气的振动、一串整数、压缩后的字节、网络上的数据包，然后再原路变回来。这条路径上每一步在做什么，决定了工程实现中大量细节的取值。采样率该设多少、一帧多长、时间戳怎么递增、打断时该清哪几个地方，答案都在这条路径上。搞不清楚，就会出现声音忽快忽慢、打断之后还多说半句这类难以定位的问题。本章沿着这段旅程走一遍：先看上行的六步，再看下行对称的六步；然后拎出三个从头到尾不变的数字。

2026-09-15 16:18:53 40

原创第10章 DataChannel 数据传输

本章详解WebRTC的DataChannel机制：它与音视频共用连接、端到端加密，零成本开启，可传输文本、二进制及切片文件。支持多通道按需配置可靠性和顺序，适用于实时文字、状态同步、控制指令等场景。语音智能体可借此替代独立WebSocket，简化架构。但需注意64KB单消息上限和发送背压问题，尤其在真实网络中验证切片与缓冲处理。

2026-09-15 16:16:04 63

原创第09章 WHIP 协议详解

WHIP协议通过一次HTTP往返完成WebRTC建连，省去传统信令的长连接与复杂逻辑。客户端发送含全部候选的SDP offer，服务端返回SDP answer并分配资源，全程仅需三次交互。其优势在于简化实现、降低维护成本，但需等待候选收集完成，建连延迟略增。在语音智能体场景中，因收发同端且为双向通信，一条sendrecv连接即可满足需求，无需配套的WHEP拉流协议。应用层消息可借DataChannel传递，避免额外连接。整体上，WHIP仅活跃于建连与挂断阶段，改造风险可控，是轻量级信令的理想选择。

2026-09-15 16:12:56 72

原创第08章 WebRTC 在 VoiceAgent 中的基本流程

本章详解WebRTC在VoiceAgent中的核心流程：通过四步协商建立连接，完成媒体与网络参数的交换；连通后音频与信令双通道并行，前者高频传输音视频，后者传递文字、状态与打断指令；整条链路分为上行识别、服务端处理、下行合成三段，WebRTC仅负责两端传输，不参与中间逻辑。建议直连服务端，避免中转层引入延迟与复杂度，便于快速定位延迟与故障。

2026-09-15 16:09:52 70

原创第07章 LLM 与 RAG 的基本原理

本文详解大语言模型（LLM）在语音智能体中的核心作用及其局限：模型无状态导致每轮对话需重拼输入，历史过长将增加成本与延迟，故需截断管理；为解决模型不知企业私有信息的问题，引入检索增强生成（RAG），通过向量库检索相关资料作为输入，使模型“开卷作答”，提升回答准确性。关键在于，模型未被修改，效果取决于检索质量。选型时应关注流式输出与首字延迟，并根据业务是否涉及私有数据决定是否启用检索。

2026-09-15 16:07:03 112

原创第05章实时语音识别的 ASR 原理

本文详解实时语音识别（ASR）原理：声音经采样、分帧、转频谱后，由声学模型逐帧猜测音素，再通过解码合并重复、去除空白符号生成文字。因流式识别只能基于已听内容预测，结果会随输入动态修正，导致“边说边改”。中文因无词边界、同音字多，难度更高。模型能力源于海量标注语料训练，准确率取决于语种匹配度，选型应优先考虑目标语种的训练数据覆盖。

2026-09-15 10:09:25 204

原创第04章断句原理：本地 VAD 与神经网络 VAD

本文详解语音智能体断句原理：基于连续静音时长（通常300–800ms）判定用户说话结束，依赖静音计数器与清零规则确保句中停顿不被误判。本地能量VAD因无法区分人声与噪声，仅适用于快速打断触发；而云端神经网络VAD具备高精度，承担关键的断句任务。二者分工明确——本地快、糙，云端准、慢，共同保障真实场景下响应的准确性与流畅性。

2026-09-15 10:00:24 125

原创第03章对话打断：VAD 原理与打断流程

本文摘自《VoiceAgent 全栈实战》原理篇，作者，清华社签约作者。读者与人交谈时，若对方说到一半跑偏了，多半会直接开口打断，对方也随即停下。这个动作在人与人之间自然到无需思考，但要让语音智能体做到同样的事，需要分别解决两个问题：机器如何知道有人开口了，以及知道之后如何让自己真正闭嘴。前一个问题由一项专门的检测技术负责，它必须在几十毫秒内给出答案，慢一步打断就失去意义。后一个问题比想象中麻烦：系统已经产生的声音同时堆在三个地方，只清理其中一处，它会若无其事地把话说完。

2026-09-14 08:39:31 164

原创第02章对话时间线与延迟分析

衡量语音智能体的响应速度，业界用的指标是首字延迟，即从用户说完最后一个字，到他听见回答第一个字之间的间隔。之所以只算到第一个字，是因为后续内容在用户收听前一句的同时就已经算好了。用户耳朵里始终有声音，整段回答说完需要多久，他并不关心。真正影响体验的是那段“说完之后的沉默”。图 2-1 中标注的首字延迟约为 1.4 s。笔者认为这个量级对用户是可以接受的：说完一句话，等一秒多就听到回应，符合日常对话的心理预期。如果实测值明显大于这个量级，就说明方案存在需要排查的问题。

2026-09-13 10:39:45 80

原创第01章 VoiceAgent 的总体架构与完整流程

VoiceAgent 由 Voice 与 Agent 两部分构成。Voice 指语音，Agent 指智能体。合起来，它描述的是一类不仅能收发语音、而且具备理解与决策能力的软件系统。单纯的语音播报或语音输入法不属于这一范畴，因为它们只完成信号与文本之间的转换，不产生判断。VoiceAgent 之所以称为智能体，关键在于链路中间接入了大语言模型（Large Language Model，LLM）：系统拿到用户说的话之后，由模型决定回应什么内容，而不是按预设脚本应答。

2026-09-13 09:58:45 167

原创第10章接入OpenCode与调试排错

前九章把 MCP Server 与 Client 都跑通,但所有验证都通过命令行脚本完成,Server 暴露的能力还没有真正进入 AI 工作流。本章把整套服务接入 OpenCode 这一开源终端 AI 编程助手,让 Tool 与 Resource 在真实对话中被调用。接入的核心动作只有一件事:写一份配置。但围绕这件事会引出生产场景中常遇到的四类故障,启动失败、握手失败、调用失败、协议异常。本章把这些故障的现象、原因与排查路径整理成可对照的清单,作为读者后续部署 MCP 服务的参考。

2026-05-19 14:26:05 882

原创第09章 HTTP/SSE模式改造与多客户端

上一章把 stdio 模式的端到端链路跑通,但 stdio 的边界也很明显,单机、单 Client、随 Client 启停。本章把 Server 改造为 HTTP/SSE 模式,解锁多 Client 共享与远程部署。迁移的关键发现是:业务代码几乎不需要改动。Tool、Resource、Prompt 的实现完全复用,差别只在mcp.run()的传输参数上。这一便利是 FastMCP 在框架层做的工作,也是 MCP 协议“传输与业务解耦”设计哲学的直接体现。

2026-05-19 14:25:29 192

原创第08章 stdio客户端实战

Server 端能力齐全后,本章把 Client 端实现接上,完成最小可运行的端到端链路。一个 MCP Server 即使写得再完整,没有 Client 来调用,所有能力都还停留在“声明”层面;唯有 Client 把这些能力调起来,链路才算闭环。本书使用 MCP Python SDK 实现 Client,基于asyncio异步模型。Client 的代码相比 Server 更短、模式也更固定,本质上就是“建立连接、列能力、调能力”三步,而后所有工程化考虑(超时、重试、错误处理)都在这个基础上扩展。

2026-05-19 14:24:58 155

原创第07章 Resource与Prompt实现

上一章把 5 个 Tool 接上后,Server 已具备执行动作的能力。本章给 Server 补上数据资源(2 个 Resource)与提示模板(2 个 Prompt)两类能力,完成整个 Server 的能力面。Resource 与 Prompt 在实现复杂度上比 Tool 简单,但设计层面的考量更多,同一份数据,做成 Tool 还是 Resource?同一类分析任务,Prompt 是否要点名具体 Tool?这些选择直接影响 Agent 工作流的稳定性与灵活性。

2026-05-19 14:24:10 149

原创第06章 Tool能力实现

数据层就绪后,本章把 5 个 Tool 的实现逐一接到 SQLite 工单库上。Tool 是 MCP 三大能力中最常用的一个,也是模型与外部世界发生交互的核心入口。5 个 Tool 涵盖三类典型用法:聚合统计()、单条详情()、列表查询()、轻量分析(三类用法在 SQL 写法、参数 schema、返回结构上各有差异,逐一展开后,读者将对 MCP Tool 的实现范式有完整认识。读完本章,读者将理解装饰器的工作机制、参数 schema 的推导规则,以及 5 个 Tool 各自的 SQL 实现要点。

2026-05-19 14:23:40 346

原创第05章数据层设计:SQLite工单库

上一章把工程骨架搭起来,本章给骨架填数据。MCP Server 本质上是个“把外部数据变成模型可读形态”的中间层,所以一切 Tool 与 Resource 的实现都要先回答一个前置问题:数据从哪里来?本书示例选用 SQLite 作为数据存储。这是个嵌入式关系型数据库,以单文件形态存在、零配置、零进程,Python 标准库直接内置sqlite3模块,不必额外安装数据库服务。这一选择纯粹基于教学便利;

2026-05-19 14:23:04 318

原创第04章开发环境与项目骨架

前三章把 MCP 的定位、能力模型、传输层逐一交代清楚,本章进入实战准备阶段,从空白目录开始,把开发环境搭起来。环境层面只关注三件事:依赖如何隔离、FastMCP 框架的最小心智模型是什么、四个核心 Python 文件如何在工程里组织。读完本章,读者将拥有一个空但完整的 MCP 项目骨架,能够成功,具备进入后续六章实战的前置条件。本章不再赘述 Python 基础;只讨论 MCP 项目特有的环境约定与目录布局。

2026-05-19 14:22:33 311

原创第03章传输层:stdio、HTTP/SSE与JSON-RPC

上一章讲清了 MCP 暴露什么,本章讨论它怎么传送。Resources、Tools、Prompts 三类能力的调用请求与响应,究竟以什么样的报文格式在 Client 与 Server 之间流动?MCP 在协议层选用 JSON-RPC 2.0 作消息骨架,在传输层提供 stdio 与 HTTP/SSE 两种通道。这一分层是 MCP 灵活性的根源,同一份 Server 实现,既可以作为本机子进程运行,也可以作为远程网络服务部署,业务代码完全不动。

2026-05-19 14:22:02 401

原创第02章三大核心概念:Resources、Tools、Prompts

上一章把 MCP 协议的定位与诞生背景讲清楚之后,本章进入它的能力模型。一个 MCP Server 究竟能“暴露什么”给 Client?这正是 MCP 与早期工具协议拉开差距的地方。MCP 把 AI 应用与外部能力之间的交互切分为三个正交维度:Resources(资源)、Tools(工具)、Prompts(提示)。三者的语义边界、触发方、生命周期都不一样,把它们混淆是初学者最常见的认知偏差。读完本章,读者将能用一句话说清三者各自的职责,并能在工单分析这一贯穿案例中找到它们的对应实例。Resources 在

2026-05-19 14:21:10 474

原创第01章 MCP协议的定位与价值

在 AI 应用开发中,语言模型本身只能处理文本,要让模型查询数据库、读取文件、调用外部接口,必须借助某种工具协议将能力暴露给模型。过去几年,各类 Agent 框架与 IDE 助手各自定义了一套工具调用规范,导致同一个功能往往需要为不同生态分别封装,集成成本随接入对象数量线性上升。Model Context Protocol(模型上下文协议,MCP)的出现意在解决这种生态割裂。它将 AI 应用与外部能力之间的连接方式标准化,把工具发现、调用、上下文传递等环节固化为统一协议;

2026-05-19 14:20:10 376

原创第10章全栈联调与排错

走到本章，读者已经在前面九章里把所有零件分别讲清楚。但分头跑通与整套跑通是两回事：Ollama、MCP Server、FastAPI、Next.js 四个进程需要按正确顺序启动，相互的端口、依赖、模型必须就位。本章把全栈联调的步骤、常见故障、调试技巧一并整理，作为读者跑通本书项目的最后一道指南。完成本章后，读者将拥有一份可重复使用的本地部署 Checklist，并具备在任意环境下迅速定位 RAG 链路故障的能力。

2026-05-17 10:45:16 552

原创第09章 Next.js 前端流式聊天界面

后端已经把 RAG 能力打包成一个 SSE 接口，最后一公里是让最终用户在浏览器中流畅地体验它。本章用 Next.js 实现一个最小可用的流式聊天界面：把用户问题通过 EventSource 发给后端，按事件类型把检索状态、参考工单与模型回答分别渲染出来。完成本章后，读者将拥有一个能跑通的电商工单问答前端，并理解 EventSource API 如何把 SSE 协议消化为浏览器中熟悉的事件回调。

2026-05-17 10:44:42 158

原创第08章 FastAPI 与 SSE 流式 RAG 后端

到目前为止，知识库、检索工具、MCP 客户端都已经就绪，但仍缺少一个面向最终用户的入口。本章用 FastAPI 把整条 RAG 链路串起来：接收前端发来的自然语言问题，调用 MCP 工具检索相关工单，构造检索增强提示词喂给 Ollama，再用 SSE 把模型的流式回答推送到前端。完成本章后，读者将拥有一个可被任意前端调用的 /llm/rag 接口，并理解 SSE 协议为何特别适合本地 LLM 这种“边算边出”的场景。

2026-05-17 10:44:09 108

原创第07章 FastMCP 把检索封装成 Agent 工具

工单知识库已经能在 Python 进程内被普通函数调用，但要让外部 Agent、Web 后端或其他语言的客户端使用这份能力，函数级别的接口不够：缺少协议、缺少描述、缺少跨进程通讯。MCP（Model Context Protocol）正是为这种场景设计的标准化协议，它把工具的描述、参数、返回值与传输层一并标准化，便于 Agent 自动发现和调用。本章用 FastMCP 把上一章的语义检索函数变成一个标准 MCP Tool，并在另一进程里写客户端验证调用。

2026-05-17 10:43:33 159

原创第06章构建工单知识库

在前面的章节中，笔者把文本切片、向量化、ChromaDB 写入查询的零件逐一调通。本章把这些零件组装到一起，搭建本书贯穿案例的核心：电商工单语义检索知识库。读者将看到一条完整工单从原始字典到向量库的全过程，并理解 ChromaDB 中文档、元数据、向量三者协同的工程细节。完成本章后，读者将拥有一个可被后续 Agent 工具直接调用的工单语义检索能力，并具备把这一思路迁移到任意业务数据上的方法。

2026-05-17 10:43:01 338

原创第05章 ChromaDB 向量数据库入门

每次手动传 embeddings 容易遗漏，更稳妥的做法是把 Ollama 嵌入封装成一个 EmbeddingFunction 注入集合，让 ChromaDB 内部自动调用。注入后，集合的 add 与 query 都会自动用 OllamaEmbedding 计算向量。读者只要确保读写双方都使用同一个 EmbeddingFunction 实例化的集合即可。注意：EmbeddingFunction 的输入是一个文本列表而非单条文本，常见错误是把 input 当作字符串处理，导致返回结构错乱。

2026-05-17 10:42:08 429

原创第04章 Embedding 向量化原理与实战

切好的文本块还停留在字符串状态，无法直接用于相似度检索。要让机器判断“用户问题”与“知识块”之间是否相关，必须先把它们映射到同一个数学空间，再用距离或夹角衡量接近程度。完成这一映射的模型叫嵌入模型，输出结果通常是几百到几千维的浮点向量。本章基于配套源码中的 test_embedding_ollama.py，讲清楚 Ollama 嵌入接口怎么调用、返回的向量如何理解、余弦相似度如何计算。完成本章后，读者能够把一组文本变成一组向量，并对任意两个文本块给出量化的相似度分数。

2026-05-17 10:41:36 337

原创第03章文本切片：为向量化准备数据

掌握了 Ollama HTTP 接口之后，读者已经可以让本地大模型回答任何问题。但模型只能基于训练数据回答，对私有知识、最新事件、企业内部文档一无所知。检索增强生成的思路是先把外部资料拆成可检索的小块，存入向量数据库，回答时按相关性把若干小块取出，与问题一起交给模型。这条链路的第一步就是文本切片。本章解释切片的必要性、常见策略与代码实现，使用配套源码中的 test_text_split.py 作为基准实现。

2026-05-17 10:41:03 426

原创第02章 Ollama HTTP API 与流式响应

在前一章中，笔者完成了 Ollama 的安装与 CLI 验证。CLI 适合人机对话调试，对应用集成来说仍然不够直接：业务代码无法读取 CLI 进程的输出，也无法控制并发与超时。Ollama 真正向应用开放的能力，是常驻在 11434 端口的 HTTP 接口。本章把这条 HTTP 通道彻底走通，让读者在不依赖任何 SDK 的前提下，用 Python 的 requests 与 httpx 实现生成、对话与流式响应解码。

2026-05-17 10:39:53 277

原创第01章 Ollama 本地大模型快速上手

如果读者曾因公司数据安全、网络延迟或调用成本，犹豫是否要把项目接入云端大模型，那么本章将给出一种本地化的解题路径。Ollama 把模型权重下载到本地磁盘，将推理过程封装为一个常驻进程，通过 HTTP 接口对外提供能力，使得在一台普通笔记本上跑起 LLM 与 Embedding 不再需要复杂的环境配置。本章先把开发机准备成可调用大模型的状态：安装运行时、拉取所需模型、用 CLI 验证生成与对话效果。完成本章后，读者将拥有一个稳定运行的本地推理服务，为后续向量化、检索增强生成、Agent 工具调用打下基础。

2026-05-17 10:39:15 400

空空如也

空空如也