项目概述用 Mastra 和 Elasticsearch 构建具备代理能力的 AI 应用先说说这个项目是干嘛的。简单讲我要做一个能把大模型、业务逻辑和搜索能力串起来的 AI 应用让它不只是能聊天还能自己规划、调用工具、翻历史记录像一个小助手一样完成多步任务。技术底座用了两个东西一个是Mastra一个专门用来编排 AI 代理的框架另一个是Elasticsearch老牌搜索引擎但它现在最强的身份其实是向量数据库——我们既要用它存业务数据的索引又要用它做语义检索和记忆存储。这个项目适合谁看两类人。第一类是已经跑通过大模型 API但觉得一个 prompt 一把梭的方式太粗糙、想玩更工程化架构的开发者第二类是对 Elasticsearch 比较熟、但想看看它怎么跟 LLM 应用结合的后端工程师。文章里我会把架构思路、核心代码、参数配置、踩坑记录全部放出来尽量让看完的人能直接照着搭一套 demo 出来。先说结论目前这套东西跑稳定之后日常问答的响应延迟可以控制在 1.5 秒左右含检索生成对业务数据的召回准确率实测比纯 embedding 检索高出 20% 以上因为加了 rerank 和过滤条件。下面展开讲。1. 整体架构设计先别急着写代码想清楚 AI 代理到底是怎么工作的1.1 核心概念AI 代理和普通聊天机器人的区别在哪很多人以为 AI 代理就是聊天机器人加个 tool call。其实不是的。聊天机器人是你给我一句话我给你一个回复是单向的、短连接的。而 AI 代理的特点是它能拆解目标、规划步骤、调用外部工具、观察结果、修正计划然后循环直到任务完成。举个例子。用户说帮我整理上季度所有客户反馈里的负面评价并输出一份摘要报告。普通聊天机器人最多帮你生成一段通用文案它看不到你的客户反馈数据。AI 代理则会把任务拆成三步检索反馈数据、筛选负面内容、生成摘要调用 Elasticsearch 执行语义检索过滤出差评相关文档把检索结果拼进 prompt让大模型总结成报告检查结果是否符合预期不满意就换个检索条件再跑一轮。这个计划-执行-观察-循环的能力就是代理区别于聊天机器人最核心的差异。它实现起来最麻烦的不是写工具函数而是编排逻辑——你总不能让开发者手写一堆 if-else 去管理状态、上下文、循环次数吧这就是 Mastra 存在的意义。1.2 技术选型思考为什么是 Mastra而不是从零写编排器我自己早期搭过一套代理应用用的方法简单粗暴写一个 Python 脚本里面用while循环 function calling拼上下文硬是把代理逻辑堆出来。问题是代码一多状态管理、错误重试、日志追踪、多代理协作全都变得一团乱。改一个功能可能要动十几个函数。Mastra 的核心价值在于把代理开发中高度重复的部分提炼成了抽象组件Agent代理、Workflow工作流、Tool工具、RAG检索增强生成、Memory记忆。它的抽象模型非常适合代理应用——你要做的不是从零搭状态机而是声明式地描述代理有哪些工具可用、执行策略是什么、每一步怎么走。更重要的是Mastra 从设计上就是TypeScript 优先的框架。对于做全栈应用或者 Node.js 服务端的团队来说这意味着 AI 逻辑可以跟业务代码无缝衔接不用跨界维护 Python 和 Node 两套体系。我自己特别喜欢这一点因为 ES 那边我本来就要用elastic/elasticsearch客户端写查询如果代理层也是 JS/TS整个链路就不用切换语言了。1.3 Elasticsearch 在这个项目里扮演的三个角色很多人把 Elasticsearch 跟日志系统划等号这是对它的刻板印象。在 AI 代理应用里ES 至少能干三件事第一业务数据检索。这是它的老本行倒排索引做全文搜索带过滤、聚合、高亮实力依旧强劲。第二个向量语义检索。ES 8.x 之后内置了dense_vector字段类型和kNN查询可以直接当向量数据库用。第三个代理记忆存储。代理跟用户对话的历史、中间的推理过程、知识片段都可以用 ES 存起来——它的索引生命周期管理ILM很适合按时间清理缓存型数据。这三个角色组合起来意味着你可以在一套基础设施上实现业务数据搜索 语义召回 记忆持久化不用额外引入 Redis、Pinecone、Postgres 来各干各的。对我来说少一套组件就少一组运维负担。2. 环境准备与基础配置把底座搭稳2.1 安装与版本选型我这次的开发环境是这样的Node.js 20.10npm 10.x一个自建的 Elasticsearch 8.11 集群三节点Mastra 用的是当时最新的 0.1.x 版。为了省事我本地用的服务版 ES 是 Docker 起的一键启动。动手之前先把依赖装好。我用pnpm因为 TS 项目里它的依赖管理更干净# 初始化项目如果是空目录 pnpm init # 安装 Mastra 核心包 pnpm add mastra/core # 安装官方 ES 客户端 pnpm add elastic/elasticsearch # 安装 OpenAI SDK或其他模型提供商 SDK按需选 pnpm add openai # devDependencies 装 TypeScript 和构建工具 pnpm add -D typescript types/node tsx一个容易踩的坑是版本兼容。Mastra 还在快速迭代期API 变动很频繁不同小版本之间可能有 breaking change。我的建议是打开项目的 GitHub Releases 页面找到跟你的使用日期最接近的一个稳定版锁定到精确版本号不要用^0.1.0这种带^的写法否则哪天pnpm install装到新版本代码可能就编译不过了。ES 这边不用装客户端层面太新或太老的东西elastic/elasticsearch8.x 系列跟 ES 8.x 集群通信完全兼容。需要注意的只有一点如果你之前用 7.x 客户端连接过 ES代码里搜索请求的参数结构有变化比如body参数被移到顶层了千万别把老代码直接复制过来。2.2 初始化 Mastra 应用骨架Mastra 提供应用生成器可以快速生成一套标准目录结构。执行pnpm dlx create-mastra-applatest my-ai-agent-app生成出来的目录大约是这样的结构my-ai-agent-app/ ├── src/ │ ├── agents/ # 代理定义 │ ├── tools/ # 代理可调用的工具 │ ├── workflows/ # 工作流编排 │ └── index.ts # 应用入口 ├── .env ├── tsconfig.json └── package.json入口文件src/index.ts里核心任务是注册我们定义的代理。我建议先用官方脚手架把最简单的一个 echo agent 跑通确认环境链路没问题再逐步加入 Elasticsearch 的调用。先跑通再扩展排查问题的范围会小很多。2.3 ES 索引设计的第一版草案在写代码之前索引设计反而最值得花时间。ES 的 mapping 一旦建好后面改起来极痛苦虽然可以重新索引但生产环境代价很大。我针对这个 AI 代理项目设计了三个索引第一个是business_kb放业务知识库文档是 RAG 的主要数据源。字段包括标题、正文内容、分类、标签、更新时间以及一个dense_vector 向量字段维度根据 embedding 模型来定下面代码里用的是 1536 维对应 OpenAI 的 text-embedding-3-large。第二个是conversation_memory存代理和用户的会话记录。字段包含会话 ID、角色、消息内容、创建时间。这个索引的写入频率高、数据增长快所以开了 ILM 策略30 天后自动删旧记录保持索引体积可控。第三个是agent_logs存代理每次执行的详细日志——调用了哪个工具、命中哪些文档、模型输出了什么。这个索引主要是调试用所以我特意把_source关掉了只存字段写起来非常快省磁盘。这三个索引的 mapping 细节我会在后面的实践章节展示但先想清楚数据从哪来、流量长什么样、存活多久是搭 ES 索引的基本功。3. 核心实现让代理学会搜索和思考3.1 定义 Agent给大模型装上一个编剧大脑代理的入口是 Agent 对象。在 Mastra 里一个 Agent 需要指定三样东西用的什么模型、有哪些工具、系统 prompt 是什么。我写了一个负责基于业务知识库回答客户问题的客服型代理简化版定义如下// src/agents/supportAgent.ts import { Agent } from mastra/core; import { openai } from ai-sdk/openai; import { esSearchTool } from ../tools/esSearchTool; import { esMemoryTool } from ../tools/esMemoryTool; export const supportAgent new Agent({ name: support-agent, model: openai(gpt-4o-mini), instructions: 你是一名专业的客服助手负责基于知识库回答客户问题。 规则 1. 只使用工具返回的数据回答问题不要编造内容。 2. 如果检索结果不足明确告诉用户暂时没有找到相关信息。 3. 回答尽量简洁、有条理分点输出。 , tools: { esSearch: esSearchTool, memory: esMemoryTool, }, });这一步看起来简单但背后的关键决策是把 ES 搜索逻辑封装成工具Tool而不是写死在代理代码里。这样做的好处是模型可以在运行时自主决定需不需要搜索、搜什么关键词、过滤条件是什么而不是由我们预先编写固定查询逻辑。不同用户问不同问题时模型会动态生成查询参数——这正是代理能力与普通检索问答的分水岭。3.2 编写 ES 搜索工具模型接口和 ES 查询之间的一层桥Tool 是 Mastra 中最常用的抽象本质上是给模型看一个带描述的 JSON schema当模型决定调用它时框架去执行对应的函数。我实现的esSearchTool职责是接收模型的检索意图转成 ES 查询返回命中结果。型如下// src/tools/esSearchTool.ts import { Tool } from mastra/core; import { z } from zod; import { client } from ../lib/esClient; // 共享的 ES 客户端实例 export const esSearchTool new Tool({ name: ES 知识库搜索, description: 在业务知识库中搜索与用户问题相关的文档返回匹配的正文片段。, args: z.object({ query: z.string().describe(搜索关键词或自然语言问题), topK: z.number().default(5).describe(返回的文档数量), category: z.string().optional().describe(按分类过滤), }), execute: async ({ query, topK, category }) { const mustClause: any[] []; if (category) { mustClause.push({ term: { category } }); } const result await client.search({ index: business_kb, size: topK, query: { bool: { must: [ { multi_match: { query, fields: [title^3, content], fuzziness: AUTO, }, }, ], filter: mustClause, }, }, highlight: { fields: { content: { fragment_size: 200, number_of_fragments: 1 } }, }, }); return (result.hits.hits ?? []).map((hit: any) ({ title: hit._source.title, content: hit.highlight?.content?.[0] ?? hit._source.content, score: hit._score, })); }, });注意这里我用了multi_matchfuzziness: AUTO。为什么不用向量检索因为导出到底用全文搜索还是向量检索取决于用户问题的类型。像退款的流程是什么这种明确的业务问题全文检索匹配效果更好速度也更快毫秒级。而用户觉得产品难用该怎么办这种语义含糊的问题才更适合走向量。最理想的设计是让代理自己判断该用哪种检索——这就需要在 prompt 里写明两种工具的区别。实际做的时候我倾向于默认走 hybrid混合检索后面会讲怎么合并分数。3.3 接入向量检索让代理具备语义理解能力只靠关键词检索代理的理解能力是有限的。比如用户说我的账号登不进去了如果知识库里有一篇文章标题是身份认证常见故障排查关键词匹配永远匹配不上这条因为表面词汇完全不重叠。向量检索能把登不进去和身份认证故障映射到向量空间的相近位置。首先在索引 mapping 里加上向量字段ES 8.11 支持的写法如下{ mappings: { properties: { title: { type: text }, content: { type: text }, category: { type: keyword }, embedding: { type: dense_vector, dims: 1536, similarity: cosine, index: true, similarity_metric: cosine } } } }写入文档时需要先调用 embedding 模型生成向量再连同原文一起写入// src/lib/embedding.ts import OpenAI from openai; const openai new OpenAI({ apiKey: process.env.OPENAI_API_KEY }); export async function generateEmbedding(text: string): Promisenumber[] { const resp await openai.embeddings.create({ model: text-embedding-3-large, input: text, }); return resp.data[0].embedding; }批量写入时建议用 ES 的 bulk API 一次性导入比逐条 index 快几十倍。我有一篇文档开始逐条写 3000 条数据用了 20 多分钟换成 bulk 分片写入后1 分钟不到就跑完了。后面同步增量数据时我也一直用 bulk。在代理工具里加一个向量检索分支const embedding await generateEmbedding(query); const knnQuery { knn: { field: embedding, query_vector: embedding, k: topK, num_candidates: 100, }, };3.4 混合检索全文和向量结果合并避免各说各话纯向量检索的另一个问题是它对专有名词、编号、精确型号不太敏感。比如用户问XK-2200 设备的固件版本是多少这种带着精确型号的问题关键词匹配需要精确匹配 XK-2200明显更可靠而向量检索可能把语义近似的其他设备文档也捞出来反而干扰模型判断。所以我最终采用的是混合检索策略。ES 提供了一个非常实用的特性RRFReciprocal Rank Fusion倒数排名融合可以简单理解为把多路召回结果按排序位置加权合并而不需要关心各路返回的原始分数量纲不一致的问题。Mastra 工具里的查询可以写成const result await client.search({ index: business_kb, size: topK, query: { bool: { must: [ { multi_match: { query, fields: [title^3, content], fuzziness: AUTO, }, }, ], filter: mustClause, }, }, knn: { field: embedding, query_vector: embedding, k: topK, num_candidates: 100, }, rank: { rrf: { window_size: 50 } }, });注意knn和query同时出现在一个search请求里再配rank.rrf这就是 ES 原生的混合检索写法。实际运行中RRF 的window_size默认是 50我测试时发现把 window_size 调大可以让长尾文档更容易浮上来调小则头部优势更明显。一般知识库问答场景50 的效果已经不错了如果想只盯着 top5 的相关性可以调到 20 左右。4. 为代理建立记忆Elasticsearch 存储会话与上下文4.1 为什么需要记忆没有上下文的代理就是金鱼现在的对话式 AI 产品用户根本不会再容忍你刚才说什么我忘了这种体验。如果你做的是一个客服代理、私人助手代理它必须记住前文。Mastra 自带 Memory 模块默认支持多种存储后端。我第一反应是直接用默认存储但想了一下既然 ES 已经在这个项目里了不如就让 ES 充当记忆存储省一个 Redis 或 Postgres。同时ES 的记忆天然能做到记忆的全文检索——比如你让代理回忆上周用户问过哪些关于退款的问题这不只是查聊天记录而是可以做语义检索召回相关内容普通 KV 存储做不到这一点。4.2 实现方案以会话 ID 为维度存取历史消息我在 ES 里建了conversation_memory索引mapping 大致如下{ mappings: { properties: { sessionId: { type: keyword }, role: { type: keyword }, content: { type: text }, ts: { type: date } } } }每次代理响应前先从 ES 拉取最近 N 条历史按ts倒序拼到 system prompt 里让模型记得上下文。响应完成后再把新的 user/assistant 消息写回 ES。伪代码如下async function getMemoryContext(sessionId: string, limit 10) { const result await client.search({ index: conversation_memory, size: limit, query: { term: { sessionId } }, sort: [{ ts: desc }], }); return result.hits.hits.map((hit: any) ${hit._source.role}: ${hit._source.content}).reverse(); } async function saveMemory(sessionId: string, role: string, content: string) { await client.index({ index: conversation_memory, document: { sessionId, role, content, ts: new Date() }, }); }这个实现虽然简单却有一个关键好处记忆是跨会话共享的。用户 ID 可以作为sessionId的前缀比如uid-12345这样即使新建一个会话代理也能靠uid-*前缀拉取这个用户的长期记忆做一个简单的画像出来。如果只想按对话隔离就用随机 uuid 作为 sessionId 即可。4.3 记忆的剪枝与总结别让上下文撑爆 tokenES 存记忆没有成本焦虑但 token 有。如果用户连续聊了 100 轮总把全部历史塞进 prompt再大的 context window 也会爆。最好的做法是分层记忆短期记忆最近 10 轮对话原文。长期记忆每隔一定轮次让模型把前面的对话汇总成摘要只存摘要文本。Mastra 的 Memory 抽象本身支持这类操作但我自己实现更可控一点。在写入新消息后检查当前 session 的累计消息数如果超过阈值就对旧消息做一次 summarize把摘要存为一条特殊 role 的记录旧的逐条记录可以存档或删除。这是代理产品上线必做的优化不然跑一阵子就会出现回答越来越慢、越来越昂贵的尴尬。5. 代理与 ES 联调的完整实操流程5.1 数据准备把业务文档切片喂给 ES知识库的数据不可能整篇整篇塞进 ES因为检索时按整篇返回喂给 LLM内容太长会让相关性和 token 开销双重失控。我的做法是先切片再向量化再批量写入。切片策略我试过几种最后用的是段落标题感知的切法。对于 Markdown 或富文本文档优先按标题层级切块对于纯文本按 500 字左右切块且带 50 字的重叠保证语义连贯。以一段简单文档举例我写了个函数模拟这个过程function splitIntoChunks(text: string, maxLen 500, overlap 50): string[] { const sentences text.match(/[^。\n][。\n]?/g) ?? []; const chunks: string[] []; let buf ; for (const sentence of sentences) { if (buf.length sentence.length maxLen buf.length 0) { chunks.push(buf.trim()); buf (buf.slice(-overlap) || ) sentence; } else { buf sentence; } } if (buf.trim()) chunks.push(buf.trim()); return chunks; }切片之后的每个 chunk都作为一条独立文档写入 EScontent字段存正文embedding字段存向量。检索返回之后拼到 prompt 里的也是这块 chunk 的内容。5.2 首次启动链路测试一口一口验证别直接跑完整对话我见过太多人搭完框架上来就问一个综合问题结果报错了都不知道是哪一环出了问题。我自己的联调顺序是这样的第一步验证 ES 数据层。先在 Kibana 或curl里直接查business_kb索引确认文档数和向量字段都已写入。第二步单独测试搜索工具。不启动 Agent直接写一个临时脚本调用esSearchTool.execute()传一个 query看返回的文档是否符合预期。这一步能在几分钟内发现检索条件是不是太宽/太窄、向量维度是否匹配。第三步在 Agent 中只挂 esSearchTool不带 memory。跑几轮对话看模型是否能正确触发工具的调用返回的最终答案有没有依据检索内容。第四步再加上 memory。此时才测试长对话的连贯性。第五步压测与性能优化。这时才关注响应延迟。每步通过后再进下一步出问题时只用在上一步找原因。链路五个环节任何一步出问题日志和定位范围都很清晰。5.3 调试技巧把代理的每一步摊开来看代理应用的调试比普通后端难因为它不是一次请求一个响应而是多轮工具调用。我强烈建议打开 Mastra 等框架的agent telemetry遥测/追踪或自写日志记录模型收到的完整 system prompt 长什么样模型发出过几次 tool call 请求参数是什么每次工具返回的结果是什么模型最终生成了什么回复。我在代码里加了一个简单的 logger每次工具调用时打印相关信息格式大致是[TOOL_CALL] esSearch with query退款流程, topK5, categoryhelp [TOOL_RESULT] hit1: 标题, score3.42, content... [LLM_OUTPUT] 根据资料退款流程分为...有了这一步模型没有按预期调用工具还是工具返回内容质量太差一眼就能区分开。很多时候代理行为不对不是因为代码 bug而是prompt 没有表达清楚——修改 instructions 然后重跑测试是我迭代最频繁的动作。6. 进阶工作流编排——把多步任务串成流水线6.1 什么时候需要 Workflow 而不是单纯 Agent ToolAgent 自己会规划步骤但那是一个自由发挥的过程模型可能今天这么走、明天那么走这对于要固定执行流程、控制每一步质量的场景来说是致命的。比如在知识库问答之前必须先执行召回 → 要让大模型对召回的多个片段做独立评分 → 分数低的直接丢弃 → 最后才喂给最终模型。这种流程如果全靠 Agent 自由发挥结果会非常不稳定。所以 Mastra 里还有一个抽象叫Workflow。简单理解Workflow 是确定性的流水线步骤和顺序由开发者决定Agent 是自由式规划步骤由模型决定。两者可以嵌套使用。6.2 搭建一个检索→重排→生成的 RAG 工作流我实现了一个固定的 RAG 工作流作用是把搜索增强生成的过程标准化。// src/workflows/ragWorkflow.ts import { Workflow } from mastra/core; import { esSearchTool } from ../tools/esSearchTool; import { rerank } from ../lib/rerank; import { openai } from ai-sdk/openai; import { generateText } from ai; const ragWorkflow new Workflow({ name: rag-workflow, steps: [ { name: retrieve, execute: async ({ context }) { const docs await esSearchTool.execute({ query: context.query, topK: 20 }); return { docs }; }, }, { name: rerank, execute: async ({ context }) { const docs context.docs; const reranked await rerank(context.query, docs); return { topDocs: reranked.slice(0, 5) }; }, }, { name: generate, execute: async ({ context }) { const { text } await generateText({ model: openai(gpt-4o-mini), system: 基于资料回答, prompt: 问题: ${context.query}\n资料:\n${context.topDocs.map(d d.content).join(\n---\n)}, }); return { answer: text }; }, }, ], });这个 Workflow 的核心在于第二步rerank。我手头没有专门的 rerank 模型就先用 GPT 充当 reranker把 retrieve 阶段召回的 20 条文档批量塞给模型让它按问题相关性打分取 top5 的文档去做后面的生成。虽然调用成本略高但效果立竿见影——之前模型经常被无关文档带偏重排后回答准确率和引用正确率都上了一个台阶。6.3 工作流里的条件分支当检索结果不足时怎么办还有一个常见场景知识库里没有答案时代理不能硬编。我在 workflow 里加了一个条件判断步骤如果 top1 文档的相关性分数低于阈值比如全文检索_score低于 0.5 或者 rerank 打分太差工作流直接进入查不到分支生成类似抱歉知识库暂时没有覆盖到这个话题建议联系人工客服的回复而不是强行生成一个可能编造事实的答案。这对客服场景尤其重要——宁可承认不知道也不能一本正经地胡说。7. 常见问题与排查技巧实录7.1 问题一向量维度不一致导致索引无法写入或检索报错ES 对 dense_vector 的维度要求极严。如果建 mapping 时写死了dims:1536但写入的 embedding 是 3072 维比如换了个模型没同步写入必然 400 报错。最坑的是这个错误有时候不是立即抛在 index 请求上而是出现在后续的kNN检索时。排查思路很简单先GET business_kb/_mapping看实际维度再检查你的 embedding 函数到底调用哪个模型、输入了什么文本。我自己就踩过一次上线前把 embedding 模型从text-embedding-3-small1536 维换成了text-embedding-3-large3072 维忘记重建索引结果线上检索直接挂了。解决办法只有一个重建索引没有捷径。7.2 问题二混合检索 RRF 后相关性和预期不符如果你用了 RRF 混合检索发现模型引用的资料偶尔驴唇不对马嘴大概率是全文检索的头部文档压过了向量召回的文档但全文那篇其实只匹配了零碎关键词。RRF 不看分数只看名次这意味着即使全文检索召回的文档非常靠前但质量不行它仍然会被算进最终结果。解决办法三个方向选一调低全文检索的字段权重加minimum_should_match要求至少匹配一定比例的分词或把 RRF 的结果再走一次 rerank 步骤只取高质量片段。7.3 问题三代理就是死活不调用工具最让人抓狂的调试场景是日志里模型一个 tool call 都没有直接对着空气回答。99% 的情况是instructions 写得不够明确。我踩过一次当时写的是你可以搜索知识库模型根本不鸟你。后来改成如果你不确定答案必须先调用 esSearch 工具搜索知识库只要用户问题是业务相关一律先搜索再回答行为立刻正常了。要记住大模型对模糊指令的诠释完全不可控工具的触发条件必须写清楚must或should最好把优先级也讲明白。7.4 问题四响应延迟高问答超过 5 秒代理应用慢通常慢在四个环节。第一个是 embedding 生成第一个第一个嵌入调用要几百毫秒第二个是 ES 检索全文和向量两个查询叠加后大索引也可能要几百毫秒第三个是 rerank 步骤调 LLM是最耗时的一环第四个是最终生成tokens 越多越慢。优化思路把 embedding 结果缓存下来同一个 query 短时间重复出现直接命中缓存ES 索引分片和 filter 条件优化rerank 用轻量小模型或者只在 top20 中取一部分做重排减少被评分的文档数如果预算允许把生成模型从 gpt-4o 换成 gpt-4o-mini 或更快的模型延迟能降一半以上。实测调优后完整链路从 6 秒左右降到了 2 秒内用户体感已经比较顺畅了。7.5 问题五ES 大规模日志与知识库混用带来的性能干扰如果你的 ES 集群上还跑着别的日志索引知识库检索的性能可能会被拖累。我遇到过某个时段检索特别慢排查发现是其他团队的大规模日志写入把集群的 IO 打满了。解决办法是物理隔离或逻辑隔离。物理隔离最简单给知识库单独一组节点或者单独一个集群。逻辑隔离就是调优先级、限制分片恢复速度、设置索引级别的index.search.idle.after等参数。如果条件有限至少把知识库索引的refresh_interval调成30s默认 1s减少大量写入对检索的影响。8. 工具选型与方案对比为什么这套组合合我的胃口8.1 Mastra vs. 自研编排 vs. 其他 AI 框架最后聊一下方案对比因为这个项目做下来我最大的体会是选型比写代码影响深远得多。自研编排听起来很酷但状态管理、失败重试、多步循环、日志追踪这些模块任何一个做不完善线上都会出大问题。而成熟的框架如 Mastra 最大的价值是把工程化细节提前替你处理好了让你能集中精力做业务逻辑和 prompt 调优。当然 Mastra 也有缺点。它迭代太快API 变动频繁生态比 LangChain 小不少社群资料少碰到冷门需求只能自己看源码。我的态度是新项目如果团队有 TS 基础且愿意拥抱变化Mastra 值得一试如果是超大团队求稳可以先观望或选更成熟的方案。但如果你是个人开发者搭 demo 或做内部工具Mastra 绝对是最快出活的选项。8.2 Elasticsearch vs. 专用向量数据库第二个方案对比是 ES 和专用向量数据库比如 Pinecone、Milvus、Qdrant怎么选。如果只做向量搜索专用向量库在某些场景下性能和运维成本确实更好。但在 RAG 场景里几乎总是需要关键词 元数据过滤 向量的组合ES 的强项是这一套它全都自带了。更别提大量业务中间件已经把数据存在 ES与其多引一套存储不如让 ES 一鱼多吃。缺点是ES 的内存和磁盘开销比专用向量库高如果数据量极大且只做纯向量召回专用方案会有优势。所以结论是混合检索、复杂过滤、业务数据耦合场景选 ES纯向量海量召回且预算敏感时再考虑专用方案。8.3 需要避开的模型能力陷阱最后想提醒一件事不要默认大模型什么都会。很多开发者在 prompt 里要求模型判断用户情感并自动决定是否升级工单乍看很智能但模型的情感判断和路由决策是黑盒非常容易出现误判。更稳妥的做法是能用规则和传统程序确定的事就别交给模型自由发挥。比如上面的案例完全可以先用 ESsentiment分析插件或者简单的关键词黑名单做第一层判断命中后再让模型介入或者直接把命中结果作为条件分支写进 workflow。代理能力强不代表你应该把所有事情都丢给它。结语一点个人体会这套项目做下来我最大的感受是AI 代理应用的开发难点不在于调用大模型本身而在于把大模型嵌进一套可靠的工程体系里。这套体系包括了检索、记忆、流程编排、日志、评估这些不那么炫酷的部分。Mastra 帮我解决了一半的工程化问题Elasticsearch 帮我解决了另一半的数据问题两者结合才把具备代理能力的 AI 应用这个目标变成了可持续迭代的代码库。我觉得 Mastra 和 ES 这套组合短期来看有一点学习成本但只要上手后面扩展各种智能应用场景都非常顺手。无论是给产品加一个客服代理还是做一个能检索内部文档的团队助手甚至做自动化的实验数据处理这个底座都能复用。如果非要给后来者一句话的建议先把你最想验证的一个场景做到端到端跑通再考虑铺开功能代理应用迭代最快的方式永远是小步快跑而不是憋大招。 
长河君 · 2026/10/22 19:30:52 · 阅读 1.2k 用Mastra与Elasticsearch构建具备代理能力的AI应用实践
项目概述用 Mastra 和 Elasticsearch 构建具备代理能力的 AI 应用先说说这个项目是干嘛的。简单讲我要做一个能把大模型、业务逻辑和搜索能力串起来的 AI 应用让它不只是能聊天还能自己规划、调用工具、翻历史记录像一个小助手一样完成多步任务。技术底座用了两个东西一个是Mastra一个专门用来编排 AI 代理的框架另一个是Elasticsearch老牌搜索引擎但它现在最强的身份其实是向量数据库——我们既要用它存业务数据的索引又要用它做语义检索和记忆存储。这个项目适合谁看两类人。第一类是已经跑通过大模型 API但觉得一个 prompt 一把梭的方式太粗糙、想玩更工程化架构的开发者第二类是对 Elasticsearch 比较熟、但想看看它怎么跟 LLM 应用结合的后端工程师。文章里我会把架构思路、核心代码、参数配置、踩坑记录全部放出来尽量让看完的人能直接照着搭一套 demo 出来。先说结论目前这套东西跑稳定之后日常问答的响应延迟可以控制在 1.5 秒左右含检索生成对业务数据的召回准确率实测比纯 embedding 检索高出 20% 以上因为加了 rerank 和过滤条件。下面展开讲。1. 整体架构设计先别急着写代码想清楚 AI 代理到底是怎么工作的1.1 核心概念AI 代理和普通聊天机器人的区别在哪很多人以为 AI 代理就是聊天机器人加个 tool call。其实不是的。聊天机器人是你给我一句话我给你一个回复是单向的、短连接的。而 AI 代理的特点是它能拆解目标、规划步骤、调用外部工具、观察结果、修正计划然后循环直到任务完成。举个例子。用户说帮我整理上季度所有客户反馈里的负面评价并输出一份摘要报告。普通聊天机器人最多帮你生成一段通用文案它看不到你的客户反馈数据。AI 代理则会把任务拆成三步检索反馈数据、筛选负面内容、生成摘要调用 Elasticsearch 执行语义检索过滤出差评相关文档把检索结果拼进 prompt让大模型总结成报告检查结果是否符合预期不满意就换个检索条件再跑一轮。这个计划-执行-观察-循环的能力就是代理区别于聊天机器人最核心的差异。它实现起来最麻烦的不是写工具函数而是编排逻辑——你总不能让开发者手写一堆 if-else 去管理状态、上下文、循环次数吧这就是 Mastra 存在的意义。1.2 技术选型思考为什么是 Mastra而不是从零写编排器我自己早期搭过一套代理应用用的方法简单粗暴写一个 Python 脚本里面用while循环 function calling拼上下文硬是把代理逻辑堆出来。问题是代码一多状态管理、错误重试、日志追踪、多代理协作全都变得一团乱。改一个功能可能要动十几个函数。Mastra 的核心价值在于把代理开发中高度重复的部分提炼成了抽象组件Agent代理、Workflow工作流、Tool工具、RAG检索增强生成、Memory记忆。它的抽象模型非常适合代理应用——你要做的不是从零搭状态机而是声明式地描述代理有哪些工具可用、执行策略是什么、每一步怎么走。更重要的是Mastra 从设计上就是TypeScript 优先的框架。对于做全栈应用或者 Node.js 服务端的团队来说这意味着 AI 逻辑可以跟业务代码无缝衔接不用跨界维护 Python 和 Node 两套体系。我自己特别喜欢这一点因为 ES 那边我本来就要用elastic/elasticsearch客户端写查询如果代理层也是 JS/TS整个链路就不用切换语言了。1.3 Elasticsearch 在这个项目里扮演的三个角色很多人把 Elasticsearch 跟日志系统划等号这是对它的刻板印象。在 AI 代理应用里ES 至少能干三件事第一业务数据检索。这是它的老本行倒排索引做全文搜索带过滤、聚合、高亮实力依旧强劲。第二个向量语义检索。ES 8.x 之后内置了dense_vector字段类型和kNN查询可以直接当向量数据库用。第三个代理记忆存储。代理跟用户对话的历史、中间的推理过程、知识片段都可以用 ES 存起来——它的索引生命周期管理ILM很适合按时间清理缓存型数据。这三个角色组合起来意味着你可以在一套基础设施上实现业务数据搜索 语义召回 记忆持久化不用额外引入 Redis、Pinecone、Postgres 来各干各的。对我来说少一套组件就少一组运维负担。2. 环境准备与基础配置把底座搭稳2.1 安装与版本选型我这次的开发环境是这样的Node.js 20.10npm 10.x一个自建的 Elasticsearch 8.11 集群三节点Mastra 用的是当时最新的 0.1.x 版。为了省事我本地用的服务版 ES 是 Docker 起的一键启动。动手之前先把依赖装好。我用pnpm因为 TS 项目里它的依赖管理更干净# 初始化项目如果是空目录 pnpm init # 安装 Mastra 核心包 pnpm add mastra/core # 安装官方 ES 客户端 pnpm add elastic/elasticsearch # 安装 OpenAI SDK或其他模型提供商 SDK按需选 pnpm add openai # devDependencies 装 TypeScript 和构建工具 pnpm add -D typescript types/node tsx一个容易踩的坑是版本兼容。Mastra 还在快速迭代期API 变动很频繁不同小版本之间可能有 breaking change。我的建议是打开项目的 GitHub Releases 页面找到跟你的使用日期最接近的一个稳定版锁定到精确版本号不要用^0.1.0这种带^的写法否则哪天pnpm install装到新版本代码可能就编译不过了。ES 这边不用装客户端层面太新或太老的东西elastic/elasticsearch8.x 系列跟 ES 8.x 集群通信完全兼容。需要注意的只有一点如果你之前用 7.x 客户端连接过 ES代码里搜索请求的参数结构有变化比如body参数被移到顶层了千万别把老代码直接复制过来。2.2 初始化 Mastra 应用骨架Mastra 提供应用生成器可以快速生成一套标准目录结构。执行pnpm dlx create-mastra-applatest my-ai-agent-app生成出来的目录大约是这样的结构my-ai-agent-app/ ├── src/ │ ├── agents/ # 代理定义 │ ├── tools/ # 代理可调用的工具 │ ├── workflows/ # 工作流编排 │ └── index.ts # 应用入口 ├── .env ├── tsconfig.json └── package.json入口文件src/index.ts里核心任务是注册我们定义的代理。我建议先用官方脚手架把最简单的一个 echo agent 跑通确认环境链路没问题再逐步加入 Elasticsearch 的调用。先跑通再扩展排查问题的范围会小很多。2.3 ES 索引设计的第一版草案在写代码之前索引设计反而最值得花时间。ES 的 mapping 一旦建好后面改起来极痛苦虽然可以重新索引但生产环境代价很大。我针对这个 AI 代理项目设计了三个索引第一个是business_kb放业务知识库文档是 RAG 的主要数据源。字段包括标题、正文内容、分类、标签、更新时间以及一个dense_vector 向量字段维度根据 embedding 模型来定下面代码里用的是 1536 维对应 OpenAI 的 text-embedding-3-large。第二个是conversation_memory存代理和用户的会话记录。字段包含会话 ID、角色、消息内容、创建时间。这个索引的写入频率高、数据增长快所以开了 ILM 策略30 天后自动删旧记录保持索引体积可控。第三个是agent_logs存代理每次执行的详细日志——调用了哪个工具、命中哪些文档、模型输出了什么。这个索引主要是调试用所以我特意把_source关掉了只存字段写起来非常快省磁盘。这三个索引的 mapping 细节我会在后面的实践章节展示但先想清楚数据从哪来、流量长什么样、存活多久是搭 ES 索引的基本功。3. 核心实现让代理学会搜索和思考3.1 定义 Agent给大模型装上一个编剧大脑代理的入口是 Agent 对象。在 Mastra 里一个 Agent 需要指定三样东西用的什么模型、有哪些工具、系统 prompt 是什么。我写了一个负责基于业务知识库回答客户问题的客服型代理简化版定义如下// src/agents/supportAgent.ts import { Agent } from mastra/core; import { openai } from ai-sdk/openai; import { esSearchTool } from ../tools/esSearchTool; import { esMemoryTool } from ../tools/esMemoryTool; export const supportAgent new Agent({ name: support-agent, model: openai(gpt-4o-mini), instructions: 你是一名专业的客服助手负责基于知识库回答客户问题。 规则 1. 只使用工具返回的数据回答问题不要编造内容。 2. 如果检索结果不足明确告诉用户暂时没有找到相关信息。 3. 回答尽量简洁、有条理分点输出。 , tools: { esSearch: esSearchTool, memory: esMemoryTool, }, });这一步看起来简单但背后的关键决策是把 ES 搜索逻辑封装成工具Tool而不是写死在代理代码里。这样做的好处是模型可以在运行时自主决定需不需要搜索、搜什么关键词、过滤条件是什么而不是由我们预先编写固定查询逻辑。不同用户问不同问题时模型会动态生成查询参数——这正是代理能力与普通检索问答的分水岭。3.2 编写 ES 搜索工具模型接口和 ES 查询之间的一层桥Tool 是 Mastra 中最常用的抽象本质上是给模型看一个带描述的 JSON schema当模型决定调用它时框架去执行对应的函数。我实现的esSearchTool职责是接收模型的检索意图转成 ES 查询返回命中结果。型如下// src/tools/esSearchTool.ts import { Tool } from mastra/core; import { z } from zod; import { client } from ../lib/esClient; // 共享的 ES 客户端实例 export const esSearchTool new Tool({ name: ES 知识库搜索, description: 在业务知识库中搜索与用户问题相关的文档返回匹配的正文片段。, args: z.object({ query: z.string().describe(搜索关键词或自然语言问题), topK: z.number().default(5).describe(返回的文档数量), category: z.string().optional().describe(按分类过滤), }), execute: async ({ query, topK, category }) { const mustClause: any[] []; if (category) { mustClause.push({ term: { category } }); } const result await client.search({ index: business_kb, size: topK, query: { bool: { must: [ { multi_match: { query, fields: [title^3, content], fuzziness: AUTO, }, }, ], filter: mustClause, }, }, highlight: { fields: { content: { fragment_size: 200, number_of_fragments: 1 } }, }, }); return (result.hits.hits ?? []).map((hit: any) ({ title: hit._source.title, content: hit.highlight?.content?.[0] ?? hit._source.content, score: hit._score, })); }, });注意这里我用了multi_matchfuzziness: AUTO。为什么不用向量检索因为导出到底用全文搜索还是向量检索取决于用户问题的类型。像退款的流程是什么这种明确的业务问题全文检索匹配效果更好速度也更快毫秒级。而用户觉得产品难用该怎么办这种语义含糊的问题才更适合走向量。最理想的设计是让代理自己判断该用哪种检索——这就需要在 prompt 里写明两种工具的区别。实际做的时候我倾向于默认走 hybrid混合检索后面会讲怎么合并分数。3.3 接入向量检索让代理具备语义理解能力只靠关键词检索代理的理解能力是有限的。比如用户说我的账号登不进去了如果知识库里有一篇文章标题是身份认证常见故障排查关键词匹配永远匹配不上这条因为表面词汇完全不重叠。向量检索能把登不进去和身份认证故障映射到向量空间的相近位置。首先在索引 mapping 里加上向量字段ES 8.11 支持的写法如下{ mappings: { properties: { title: { type: text }, content: { type: text }, category: { type: keyword }, embedding: { type: dense_vector, dims: 1536, similarity: cosine, index: true, similarity_metric: cosine } } } }写入文档时需要先调用 embedding 模型生成向量再连同原文一起写入// src/lib/embedding.ts import OpenAI from openai; const openai new OpenAI({ apiKey: process.env.OPENAI_API_KEY }); export async function generateEmbedding(text: string): Promisenumber[] { const resp await openai.embeddings.create({ model: text-embedding-3-large, input: text, }); return resp.data[0].embedding; }批量写入时建议用 ES 的 bulk API 一次性导入比逐条 index 快几十倍。我有一篇文档开始逐条写 3000 条数据用了 20 多分钟换成 bulk 分片写入后1 分钟不到就跑完了。后面同步增量数据时我也一直用 bulk。在代理工具里加一个向量检索分支const embedding await generateEmbedding(query); const knnQuery { knn: { field: embedding, query_vector: embedding, k: topK, num_candidates: 100, }, };3.4 混合检索全文和向量结果合并避免各说各话纯向量检索的另一个问题是它对专有名词、编号、精确型号不太敏感。比如用户问XK-2200 设备的固件版本是多少这种带着精确型号的问题关键词匹配需要精确匹配 XK-2200明显更可靠而向量检索可能把语义近似的其他设备文档也捞出来反而干扰模型判断。所以我最终采用的是混合检索策略。ES 提供了一个非常实用的特性RRFReciprocal Rank Fusion倒数排名融合可以简单理解为把多路召回结果按排序位置加权合并而不需要关心各路返回的原始分数量纲不一致的问题。Mastra 工具里的查询可以写成const result await client.search({ index: business_kb, size: topK, query: { bool: { must: [ { multi_match: { query, fields: [title^3, content], fuzziness: AUTO, }, }, ], filter: mustClause, }, }, knn: { field: embedding, query_vector: embedding, k: topK, num_candidates: 100, }, rank: { rrf: { window_size: 50 } }, });注意knn和query同时出现在一个search请求里再配rank.rrf这就是 ES 原生的混合检索写法。实际运行中RRF 的window_size默认是 50我测试时发现把 window_size 调大可以让长尾文档更容易浮上来调小则头部优势更明显。一般知识库问答场景50 的效果已经不错了如果想只盯着 top5 的相关性可以调到 20 左右。4. 为代理建立记忆Elasticsearch 存储会话与上下文4.1 为什么需要记忆没有上下文的代理就是金鱼现在的对话式 AI 产品用户根本不会再容忍你刚才说什么我忘了这种体验。如果你做的是一个客服代理、私人助手代理它必须记住前文。Mastra 自带 Memory 模块默认支持多种存储后端。我第一反应是直接用默认存储但想了一下既然 ES 已经在这个项目里了不如就让 ES 充当记忆存储省一个 Redis 或 Postgres。同时ES 的记忆天然能做到记忆的全文检索——比如你让代理回忆上周用户问过哪些关于退款的问题这不只是查聊天记录而是可以做语义检索召回相关内容普通 KV 存储做不到这一点。4.2 实现方案以会话 ID 为维度存取历史消息我在 ES 里建了conversation_memory索引mapping 大致如下{ mappings: { properties: { sessionId: { type: keyword }, role: { type: keyword }, content: { type: text }, ts: { type: date } } } }每次代理响应前先从 ES 拉取最近 N 条历史按ts倒序拼到 system prompt 里让模型记得上下文。响应完成后再把新的 user/assistant 消息写回 ES。伪代码如下async function getMemoryContext(sessionId: string, limit 10) { const result await client.search({ index: conversation_memory, size: limit, query: { term: { sessionId } }, sort: [{ ts: desc }], }); return result.hits.hits.map((hit: any) ${hit._source.role}: ${hit._source.content}).reverse(); } async function saveMemory(sessionId: string, role: string, content: string) { await client.index({ index: conversation_memory, document: { sessionId, role, content, ts: new Date() }, }); }这个实现虽然简单却有一个关键好处记忆是跨会话共享的。用户 ID 可以作为sessionId的前缀比如uid-12345这样即使新建一个会话代理也能靠uid-*前缀拉取这个用户的长期记忆做一个简单的画像出来。如果只想按对话隔离就用随机 uuid 作为 sessionId 即可。4.3 记忆的剪枝与总结别让上下文撑爆 tokenES 存记忆没有成本焦虑但 token 有。如果用户连续聊了 100 轮总把全部历史塞进 prompt再大的 context window 也会爆。最好的做法是分层记忆短期记忆最近 10 轮对话原文。长期记忆每隔一定轮次让模型把前面的对话汇总成摘要只存摘要文本。Mastra 的 Memory 抽象本身支持这类操作但我自己实现更可控一点。在写入新消息后检查当前 session 的累计消息数如果超过阈值就对旧消息做一次 summarize把摘要存为一条特殊 role 的记录旧的逐条记录可以存档或删除。这是代理产品上线必做的优化不然跑一阵子就会出现回答越来越慢、越来越昂贵的尴尬。5. 代理与 ES 联调的完整实操流程5.1 数据准备把业务文档切片喂给 ES知识库的数据不可能整篇整篇塞进 ES因为检索时按整篇返回喂给 LLM内容太长会让相关性和 token 开销双重失控。我的做法是先切片再向量化再批量写入。切片策略我试过几种最后用的是段落标题感知的切法。对于 Markdown 或富文本文档优先按标题层级切块对于纯文本按 500 字左右切块且带 50 字的重叠保证语义连贯。以一段简单文档举例我写了个函数模拟这个过程function splitIntoChunks(text: string, maxLen 500, overlap 50): string[] { const sentences text.match(/[^。\n][。\n]?/g) ?? []; const chunks: string[] []; let buf ; for (const sentence of sentences) { if (buf.length sentence.length maxLen buf.length 0) { chunks.push(buf.trim()); buf (buf.slice(-overlap) || ) sentence; } else { buf sentence; } } if (buf.trim()) chunks.push(buf.trim()); return chunks; }切片之后的每个 chunk都作为一条独立文档写入 EScontent字段存正文embedding字段存向量。检索返回之后拼到 prompt 里的也是这块 chunk 的内容。5.2 首次启动链路测试一口一口验证别直接跑完整对话我见过太多人搭完框架上来就问一个综合问题结果报错了都不知道是哪一环出了问题。我自己的联调顺序是这样的第一步验证 ES 数据层。先在 Kibana 或curl里直接查business_kb索引确认文档数和向量字段都已写入。第二步单独测试搜索工具。不启动 Agent直接写一个临时脚本调用esSearchTool.execute()传一个 query看返回的文档是否符合预期。这一步能在几分钟内发现检索条件是不是太宽/太窄、向量维度是否匹配。第三步在 Agent 中只挂 esSearchTool不带 memory。跑几轮对话看模型是否能正确触发工具的调用返回的最终答案有没有依据检索内容。第四步再加上 memory。此时才测试长对话的连贯性。第五步压测与性能优化。这时才关注响应延迟。每步通过后再进下一步出问题时只用在上一步找原因。链路五个环节任何一步出问题日志和定位范围都很清晰。5.3 调试技巧把代理的每一步摊开来看代理应用的调试比普通后端难因为它不是一次请求一个响应而是多轮工具调用。我强烈建议打开 Mastra 等框架的agent telemetry遥测/追踪或自写日志记录模型收到的完整 system prompt 长什么样模型发出过几次 tool call 请求参数是什么每次工具返回的结果是什么模型最终生成了什么回复。我在代码里加了一个简单的 logger每次工具调用时打印相关信息格式大致是[TOOL_CALL] esSearch with query退款流程, topK5, categoryhelp [TOOL_RESULT] hit1: 标题, score3.42, content... [LLM_OUTPUT] 根据资料退款流程分为...有了这一步模型没有按预期调用工具还是工具返回内容质量太差一眼就能区分开。很多时候代理行为不对不是因为代码 bug而是prompt 没有表达清楚——修改 instructions 然后重跑测试是我迭代最频繁的动作。6. 进阶工作流编排——把多步任务串成流水线6.1 什么时候需要 Workflow 而不是单纯 Agent ToolAgent 自己会规划步骤但那是一个自由发挥的过程模型可能今天这么走、明天那么走这对于要固定执行流程、控制每一步质量的场景来说是致命的。比如在知识库问答之前必须先执行召回 → 要让大模型对召回的多个片段做独立评分 → 分数低的直接丢弃 → 最后才喂给最终模型。这种流程如果全靠 Agent 自由发挥结果会非常不稳定。所以 Mastra 里还有一个抽象叫Workflow。简单理解Workflow 是确定性的流水线步骤和顺序由开发者决定Agent 是自由式规划步骤由模型决定。两者可以嵌套使用。6.2 搭建一个检索→重排→生成的 RAG 工作流我实现了一个固定的 RAG 工作流作用是把搜索增强生成的过程标准化。// src/workflows/ragWorkflow.ts import { Workflow } from mastra/core; import { esSearchTool } from ../tools/esSearchTool; import { rerank } from ../lib/rerank; import { openai } from ai-sdk/openai; import { generateText } from ai; const ragWorkflow new Workflow({ name: rag-workflow, steps: [ { name: retrieve, execute: async ({ context }) { const docs await esSearchTool.execute({ query: context.query, topK: 20 }); return { docs }; }, }, { name: rerank, execute: async ({ context }) { const docs context.docs; const reranked await rerank(context.query, docs); return { topDocs: reranked.slice(0, 5) }; }, }, { name: generate, execute: async ({ context }) { const { text } await generateText({ model: openai(gpt-4o-mini), system: 基于资料回答, prompt: 问题: ${context.query}\n资料:\n${context.topDocs.map(d d.content).join(\n---\n)}, }); return { answer: text }; }, }, ], });这个 Workflow 的核心在于第二步rerank。我手头没有专门的 rerank 模型就先用 GPT 充当 reranker把 retrieve 阶段召回的 20 条文档批量塞给模型让它按问题相关性打分取 top5 的文档去做后面的生成。虽然调用成本略高但效果立竿见影——之前模型经常被无关文档带偏重排后回答准确率和引用正确率都上了一个台阶。6.3 工作流里的条件分支当检索结果不足时怎么办还有一个常见场景知识库里没有答案时代理不能硬编。我在 workflow 里加了一个条件判断步骤如果 top1 文档的相关性分数低于阈值比如全文检索_score低于 0.5 或者 rerank 打分太差工作流直接进入查不到分支生成类似抱歉知识库暂时没有覆盖到这个话题建议联系人工客服的回复而不是强行生成一个可能编造事实的答案。这对客服场景尤其重要——宁可承认不知道也不能一本正经地胡说。7. 常见问题与排查技巧实录7.1 问题一向量维度不一致导致索引无法写入或检索报错ES 对 dense_vector 的维度要求极严。如果建 mapping 时写死了dims:1536但写入的 embedding 是 3072 维比如换了个模型没同步写入必然 400 报错。最坑的是这个错误有时候不是立即抛在 index 请求上而是出现在后续的kNN检索时。排查思路很简单先GET business_kb/_mapping看实际维度再检查你的 embedding 函数到底调用哪个模型、输入了什么文本。我自己就踩过一次上线前把 embedding 模型从text-embedding-3-small1536 维换成了text-embedding-3-large3072 维忘记重建索引结果线上检索直接挂了。解决办法只有一个重建索引没有捷径。7.2 问题二混合检索 RRF 后相关性和预期不符如果你用了 RRF 混合检索发现模型引用的资料偶尔驴唇不对马嘴大概率是全文检索的头部文档压过了向量召回的文档但全文那篇其实只匹配了零碎关键词。RRF 不看分数只看名次这意味着即使全文检索召回的文档非常靠前但质量不行它仍然会被算进最终结果。解决办法三个方向选一调低全文检索的字段权重加minimum_should_match要求至少匹配一定比例的分词或把 RRF 的结果再走一次 rerank 步骤只取高质量片段。7.3 问题三代理就是死活不调用工具最让人抓狂的调试场景是日志里模型一个 tool call 都没有直接对着空气回答。99% 的情况是instructions 写得不够明确。我踩过一次当时写的是你可以搜索知识库模型根本不鸟你。后来改成如果你不确定答案必须先调用 esSearch 工具搜索知识库只要用户问题是业务相关一律先搜索再回答行为立刻正常了。要记住大模型对模糊指令的诠释完全不可控工具的触发条件必须写清楚must或should最好把优先级也讲明白。7.4 问题四响应延迟高问答超过 5 秒代理应用慢通常慢在四个环节。第一个是 embedding 生成第一个第一个嵌入调用要几百毫秒第二个是 ES 检索全文和向量两个查询叠加后大索引也可能要几百毫秒第三个是 rerank 步骤调 LLM是最耗时的一环第四个是最终生成tokens 越多越慢。优化思路把 embedding 结果缓存下来同一个 query 短时间重复出现直接命中缓存ES 索引分片和 filter 条件优化rerank 用轻量小模型或者只在 top20 中取一部分做重排减少被评分的文档数如果预算允许把生成模型从 gpt-4o 换成 gpt-4o-mini 或更快的模型延迟能降一半以上。实测调优后完整链路从 6 秒左右降到了 2 秒内用户体感已经比较顺畅了。7.5 问题五ES 大规模日志与知识库混用带来的性能干扰如果你的 ES 集群上还跑着别的日志索引知识库检索的性能可能会被拖累。我遇到过某个时段检索特别慢排查发现是其他团队的大规模日志写入把集群的 IO 打满了。解决办法是物理隔离或逻辑隔离。物理隔离最简单给知识库单独一组节点或者单独一个集群。逻辑隔离就是调优先级、限制分片恢复速度、设置索引级别的index.search.idle.after等参数。如果条件有限至少把知识库索引的refresh_interval调成30s默认 1s减少大量写入对检索的影响。8. 工具选型与方案对比为什么这套组合合我的胃口8.1 Mastra vs. 自研编排 vs. 其他 AI 框架最后聊一下方案对比因为这个项目做下来我最大的体会是选型比写代码影响深远得多。自研编排听起来很酷但状态管理、失败重试、多步循环、日志追踪这些模块任何一个做不完善线上都会出大问题。而成熟的框架如 Mastra 最大的价值是把工程化细节提前替你处理好了让你能集中精力做业务逻辑和 prompt 调优。当然 Mastra 也有缺点。它迭代太快API 变动频繁生态比 LangChain 小不少社群资料少碰到冷门需求只能自己看源码。我的态度是新项目如果团队有 TS 基础且愿意拥抱变化Mastra 值得一试如果是超大团队求稳可以先观望或选更成熟的方案。但如果你是个人开发者搭 demo 或做内部工具Mastra 绝对是最快出活的选项。8.2 Elasticsearch vs. 专用向量数据库第二个方案对比是 ES 和专用向量数据库比如 Pinecone、Milvus、Qdrant怎么选。如果只做向量搜索专用向量库在某些场景下性能和运维成本确实更好。但在 RAG 场景里几乎总是需要关键词 元数据过滤 向量的组合ES 的强项是这一套它全都自带了。更别提大量业务中间件已经把数据存在 ES与其多引一套存储不如让 ES 一鱼多吃。缺点是ES 的内存和磁盘开销比专用向量库高如果数据量极大且只做纯向量召回专用方案会有优势。所以结论是混合检索、复杂过滤、业务数据耦合场景选 ES纯向量海量召回且预算敏感时再考虑专用方案。8.3 需要避开的模型能力陷阱最后想提醒一件事不要默认大模型什么都会。很多开发者在 prompt 里要求模型判断用户情感并自动决定是否升级工单乍看很智能但模型的情感判断和路由决策是黑盒非常容易出现误判。更稳妥的做法是能用规则和传统程序确定的事就别交给模型自由发挥。比如上面的案例完全可以先用 ESsentiment分析插件或者简单的关键词黑名单做第一层判断命中后再让模型介入或者直接把命中结果作为条件分支写进 workflow。代理能力强不代表你应该把所有事情都丢给它。结语一点个人体会这套项目做下来我最大的感受是AI 代理应用的开发难点不在于调用大模型本身而在于把大模型嵌进一套可靠的工程体系里。这套体系包括了检索、记忆、流程编排、日志、评估这些不那么炫酷的部分。Mastra 帮我解决了一半的工程化问题Elasticsearch 帮我解决了另一半的数据问题两者结合才把具备代理能力的 AI 应用这个目标变成了可持续迭代的代码库。我觉得 Mastra 和 ES 这套组合短期来看有一点学习成本但只要上手后面扩展各种智能应用场景都非常顺手。无论是给产品加一个客服代理还是做一个能检索内部文档的团队助手甚至做自动化的实验数据处理这个底座都能复用。如果非要给后来者一句话的建议先把你最想验证的一个场景做到端到端跑通再考虑铺开功能代理应用迭代最快的方式永远是小步快跑而不是憋大招。