用 LangChain / LangGraph 写 Agent,最难受的是那种「盲盒感」------它到底调用了哪个工具?每一步耗时多少?流式输出烧了多少 Token?错了是错在检索、错在提示词,还是错在模型?
如果你无法度量它,你就无法管理它。
这篇用两个能直接跑的 demo,把 LangSmith 从「看一条 Trace」一路讲到「拿 LLM 当裁判,批量给 RAG 打分」:调试靠 Tracing,上线靠 Monitoring,优化靠 Dataset + Evaluator。
一、为什么 Agent 需要一块「仪表盘」
LangChain / LangGraph 把 Agent 的编排变得很轻:声明状态、写节点、连边、invoke(),一个能调工具的 Agent 就跑起来了。
但跑起来之后,你很快会陷入三个问题:
- 它刚才到底做了什么? 调了
search_docs还是refund?参数是什么?返回了什么? - 慢在哪一步? 整体 8 秒,是检索 1 秒、模型 7 秒,还是工具重试了三次?
- 贵在哪一步? 一次请求消耗了多少 prompt token、多少 completion token?换了模型是省了还是更贵了?
console.log 能回答一部分,但它回答不了「跨多次运行的趋势」,也回答不了「这次改动之后,回答质量是变好了还是变差了」。
这就是可观测性要解决的事。LangSmith 是 LangChain 官方的可观测平台,它的关键优势是协议打通 :只要你用的是 langchain / langgraph,SDK 会自动把每一步执行上报成一条 Trace,业务代码几乎零改动。
先把它的核心能力拆成四块,后面每一块都会落到具体代码:
| 能力 | 解决什么 | 本文对应 |
|---|---|---|
| Tracing | 单次 Agent 执行的黑盒,逐步展开 | 第二、三节 |
| Monitoring | 多次运行的趋势:错误率、耗时、Token 成本 | 第三节 |
| Datasets | 固定的「问题 → 标准答案」样本集 | 第八节 |
| Evaluators | 用 LLM 当裁判,给回答自动打分 | 第九、十节 |
一句话概括它们的关系:
Tracing 让你看见「这次发生了什么」,Monitoring 让你看见「一直以来怎么样」,Dataset + Evaluator 让你回答「改完到底好不好」。
二、第一步:不改业务代码,先看见一条 Trace
2.1 配置就三行
LangSmith 的接入方式简单到有点反直觉------业务代码一行都不用改 ,在 .env 里配好即可:
bash
# .env
LANGCHAIN_TRACING_V2=true
LANGCHAIN_API_KEY=lsv2_pt_xxxxxxxx
LANGCHAIN_PROJECT=langsmith-demo
LANGCHAIN_TRACING_V2=true:打开自动追踪;LANGCHAIN_API_KEY:在 LangSmith 控制台创建的 API Key;LANGCHAIN_PROJECT:这条 Trace 归到哪个项目,按项目分栏看。
新版本 SDK 也支持
LANGSMITH_TRACING/LANGSMITH_API_KEY/LANGSMITH_PROJECT这组新名字,老名字LANGCHAIN_*仍然兼容。本文沿用 demo 里的老名字,两者选一组即可。
有一个细节必须说清楚:import "dotenv/config" 要放在入口文件的第一行。
js
import "dotenv/config"; // ← 必须最先执行,让环境变量在 SDK 初始化前就位
import { StateGraph } from "@langchain/langgraph";
ESM 的 import 会被提升并从头到尾求值,dotenv/config 排第一,才能保证 langsmith 的 tracer 在模块加载时读到 LANGCHAIN_API_KEY。写在后面不是一定出错,但一旦 SDK 在别处被提前加载,就会出现「日志里没有任何报错,Trace 也没有」的静默失败------这是排查时最费时间的一类问题。
2.2 一个「故意跑错」的图
demo/src/trigger-error.mjs 是专门用来验证 Trace 的最小例子:两个节点,第一个正常,第二个直接抛错。
js
// demo/src/trigger-error.mjs
import "dotenv/config";
import { Annotation, END, START, StateGraph } from "@langchain/langgraph";
const StateAnnotation = Annotation.Root({
text: Annotation({
reducer: (_prev, next) => next,
default: () => "",
}),
});
// 正常节点
const stepOk = (state) => ({ text: `${state.text}[ok]` });
// 故意失败的节点:没有返回值,直接抛错
const stepThrow = () => {
throw new Error("DemoError:节点内故意跑错:(trigger-error.mjs)");
};
const graph = new StateGraph(StateAnnotation)
.addNode("step_ok", stepOk)
.addNode("step_throw", stepThrow)
.addEdge(START, "step_ok")
.addEdge("step_ok", "step_throw")
.addEdge("step_throw", END)
.compile();
try {
await graph.invoke({ text: "start" });
console.log("不应执行");
} catch (err) {
console.error("已捕获:", err?.message ?? err);
process.exitCode = 1;
}
bash
node src/trigger-error.mjs
终端输出:
go
已捕获: DemoError:节点内故意跑错:(trigger-error.mjs)
终端里就这么一行,信息量几乎为零。但打开 LangSmith 对应项目,你会看到一条完整的执行树。
2.3 Trace 里有什么
这条 Trace 的结构大致是这样:
每一层都记录了:
| 字段 | 内容 |
|---|---|
| Input / Output | 节点收到的 state、返回的 state |
| Start / End | 开始结束时间,以及这段的耗时 |
| Error | 是否报错、错误信息、堆栈 |
| Run Type | 这一段是 chain / llm / tool / retriever / embedding... |
| Token | 涉及 LLM 调用时的 prompt / completion token 数 |
step_ok 的输入是 { text: "start" },输出是 { text: "start[ok]" };step_throw 上挂着一个红色的 Error,点开就是完整的堆栈,直接定位到 trigger-error.mjs 的那一行。
这就是从「终端里一行错误信息」到「整条执行链路可回放」的差别。 Agent 出错时,不用再靠猜和加日志。
三、读懂 Trace:Run Type、Graph 视图与 Monitoring
3.1 Trace 是一棵树,每个节点是一个 Run
LangSmith 把一次执行拆成若干 Run,按类型区分:
| Run Type | 对应什么 | 典型关注点 |
|---|---|---|
chain |
链 / 节点 / 编排层 | 这一段的输入输出、耗时 |
llm |
一次模型调用 | prompt 全文、token 用量、延迟 |
tool |
一次工具调用 | 参数、返回值、是否失败 |
retriever |
一次检索 | query、召回的文档、耗时 |
embedding / prompt / parser |
向量化、提示词渲染、输出解析 | 各子步骤的输入输出 |
嵌套关系就是调用关系:图里调了模型,模型下面可能还有 prompt 模板的 run。点开某一层,看到的永远是「这一层的输入是什么、输出是什么、花了多久」。
这也是 LangSmith 比 console.log 强的地方:日志是线性的,Trace 是有结构的。一次 RAG 请求里,「检索到的四段文本」和「最终答案」被放在正确的层级上,因果关系一眼可见。
3.2 Graph 视图:把这次运行「画」出来
对于 LangGraph,LangSmith 还能把图结构直接渲染出来,并高亮这次实际走过的路径。
节点一多,光靠读代码确认「有没有走错分支」很费劲;在 Graph 视图里,走过的节点、每条边的耗时都标得清清楚楚。哪个节点是耗时大头,不用算。
3.3 Monitoring:从「这一次」到「一直」
单条 Trace 解决个案,Monitoring 解决趋势。按项目、时间范围、tag 过滤之后,你能看到:
- 调用量 与错误率的曲线;
- P50 / P99 延迟------平均值会掩盖长尾,P99 才代表用户真实体验;
- Token 消耗与成本,按模型拆分;
- 出错最多的 run、最慢的 run,点进去直接跳到对应 Trace。
一个很实用的用法:给不同版本打上不同 tag(或用不同的 LANGCHAIN_PROJECT),上线前后对比错误率和耗时,比凭感觉判断靠谱得多。
四、从「能看见」到「能打分」:为什么 RAG 一定要量化评估
Tracing 能告诉你「这次检索了什么、答了什么」,但回答不了一个问题:
答得对不对?好不好?
RAG 的链路有两段,两段都可能坏,而且坏的方式完全不同:
| 出问题的地方 | 表现 | 光看 Trace 能发现吗 |
|---|---|---|
| 召回错了 | 检索到的文档和问题无关,模型只能硬编 | 能看到召回了什么,但判断不了「够不够相关」 |
| 召回了但没用上 | 上下文正确,模型却答漏了、答偏了 | 很难,需要逐条对照 |
| 模型幻觉 | 上下文里没有的信息,模型自己编出来 | 很难,人工核对成本极高 |
人工一条条看回答,12 条还行,1200 条就不现实了。标准解法是:
Dataset 存「问题 + 标准答案」,Evaluator 用 LLM 当裁判自动打分,批量跑、可重复、可对比。
下面用一个电商客服 RAG 把整条链路走通。知识库是 data/ 下的几份 Markdown(售后、物流、支付、会员、质保),内容足够真实,也足够容易踩坑。
五、Step 1:把知识库灌进 Milvus
rag-demo/src/milvus_insert.mjs 做的事:读文档 → 切块 → 向量化 → 建集合 → 建索引 → 写入。
5.1 读文档与切块
js
// rag-demo/src/milvus_insert.mjs(节选)
const files = readdirSync(dataDir).filter((f) => /\.(text|md)$/.test(f));
const docs = files.map((f) => ({
pageContent: readFileSync(join(dataDir, f), "utf-8"),
metadata: { source: f },
}));
const splitter = new RecursiveCharacterTextSplitter({
chunkSize: 500,
chunkOverlap: 50,
});
return splitter.splitDocuments(docs);
chunkSize: 500、chunkOverlap: 50 是一组常见的起点:块太大,检索精度下降、上下文浪费;块太小,语义被切断、回答缺信息。metadata.source 保留原始文件名,后面评估和排查时能追溯「这句话到底出自哪份文档」。
5.2 向量化:用 OpenAI 兼容接口接国内模型
js
const embeddings = new OpenAIEmbeddings({
apiKey: process.env.OPENAI_API_KEY,
model: process.env.EMBEDDING_MODEL ?? "text-embedding-v3",
configuration: {
baseURL: process.env.OPENAI_BASE_URL, // DashScope 兼容模式
},
});
这里用的是 DashScope 的 text-embedding-v3(OpenAI 兼容接口),换成任何兼容 OpenAI 协议的 embedding 服务,改 baseURL 和 model 即可。
5.3 建集合与索引
js
const dim = vectors[0].length;
await client.createCollection({
collection_name: COLLECTION,
fields: [
{ name: "langchain_primaryid", is_primary_key: true, data_type: DataType.Int64, autoID: true },
{ name: "langchain_vector", data_type: DataType.FloatVector, dim },
{ name: "langchain_text", data_type: DataType.VarChar, max_length: 8000 },
{ name: "source", data_type: DataType.VarChar, max_length: 256 },
],
});
await client.createIndex({
collection_name: COLLECTION,
field_name: "langchain_vector",
index_type: IndexType.IVF_FLAT,
metric_type: MetricType.L2,
params: { nlist: 128 },
});
await client.loadCollection({ collection_name: COLLECTION });
几个点值得留意:
- 维数是从真实向量里读出来的 (
vectors[0].length),不是写死的常量,换 embedding 模型不会对不上; - 主键用
autoID,写入时不用自己维护 ID; - 索引用
IVF_FLAT + L2,nlist: 128是中小规模数据的常规配置; - 建完索引必须
loadCollection,集合才能被查询。
脚本会先检查集合是否存在,存在就先 dropCollection,然后全量重建。这在数据量不大的知识库场景里最省心:改完文档重跑一遍脚本就行。
bash
node src/milvus_insert.mjs
终端依次打印文件列表、切块结果、向量、Inserted N records。
顺带一句:如果用的是 Zilliz Cloud 的免费集群,要留意闲置回收。数据真丢了也不用慌,
milvus_insert.mjs本来就是全量重建,重跑一遍就回来了------这也是「知识库必须能从源文件重建」的价值。
六、Step 2:把「检索 → 生成」编成一张图
rag-demo/src/rag_agent.mjs 是整个 demo 的核心。它没有用现成的 RetrievalQA 链,而是用 LangGraph 把两步显式画出来------因为只有拆成节点,Trace 里才能分别看到检索和生成的耗时、输入输出。
6.1 状态:问题、上下文、答案
js
const GraphState = Annotation.Root({
question: Annotation,
context: Annotation,
answer: Annotation,
});
三个字段对应三个环节的产物,结构简单,但信息完整。
6.2 两个节点
js
// 检索节点
async function retrieve(state) {
const docs = await retriever.invoke(state.question);
return { context: docs };
}
// 生成节点
async function generate(state) {
const contextText = state.context.map((d) => d.pageContent).join("\n\n");
const answer = await chain.invoke({
context: contextText,
question: state.question,
});
return { answer };
}
检索节点把召回的 Document[] 放进 context,生成节点把它拼成一段文本,和问题一起交给模型。
6.3 提示词:把「不知道」写进规则
js
const prompt = ChatPromptTemplate.fromMessages([
[
"system",
`你是客服助手。仅根据下面[上下文]回答:上下文没有的信息请明确说不知道,不要编造。
上下文: {context}`,
],
["human", "{question}"],
]);
const chain = RunnableSequence.from([prompt, llm, new StringOutputParser()]);
「仅根据上下文回答,没有就说不知道」是 RAG 防幻觉的第一道闸门。注意它只是第一道------模型会不会遵守,要靠后面的 groundedness 评估来验证。
llm 用 temperature: 0,客服场景要的是稳定复现,不是发挥。
6.4 连成图
js
const workflow = new StateGraph(GraphState)
.addNode("retrieve", retrieve)
.addNode("generate", generate)
.addEdge(START, "retrieve")
.addEdge("retrieve", "generate")
.addEdge("generate", END);
export const ragApp = workflow.compile();
6.5 对外只暴露一个 ask()
js
export async function ask(question) {
const result = await ragApp.invoke({ question });
return {
answer: result.answer,
context: result.context ?? [],
};
}
注意这里同时返回了 answer 和 context。 这不是顺手,而是为评估服务的:后面的 groundedness(回答是否有据)和 retrieval relevance(召回是否相关)两个评估器,都需要拿到 context。只返回答案,评估就缺了一条腿。
跑一句看看:
bash
node src/cli.mjs 无理由退货要在几天内?
js
// src/cli.mjs
const { answer } = await ask(question);
console.log(answer);
七、Step 3:造一份「标准答案」数据集
评估的前提是固定的考卷。今天用这 12 道题,明天模型换了、提示词改了,还用这 12 道题,分数才有可比性。
rag-demo/src/eval/build_dataset.mjs 把「问题 + 标准答案」写死成数组,上传到 LangSmith 的 Dataset:
js
const EXAMPLES = [
{
inputs: { question: "无理由退货要在几天内申请?" },
outputs: { answer: "自签收之日起 7 天内支持无理由退货。" },
},
// ... 共 12 条,覆盖退货、换货、运费、发货、支付、价保、会员、积分、保修、客服
];
js
const client = new Client({ apiKey: process.env.LANGCHAIN_API_KEY });
let dataset;
try {
dataset = await client.readDataset({ datasetName: DATASET_NAME });
console.log("数据集已存在");
} catch (err) {
dataset = await client.createDataset(DATASET_NAME, {
description: "RAG Agent 回归评估集",
});
console.log("已创建数据集");
}
const created = await client.createExamples(
EXAMPLES.map((e) => ({
dataset_id: dataset.id,
inputs: e.inputs,
outputs: e.outputs,
}))
);
console.log(`已创建 ${created.length} 条样例`);
bash
node src/eval/build_dataset.mjs
跑到 LangSmith 的 Datasets & Experiments 页面,能看到 rag-eval-v1 下 12 条样例,每条都是一个 inputs / outputs 对。
这批题目的设计有讲究:标准答案必须能从 data/ 里找到出处。如果标准答案本身就是模型编的,评估就从「检查幻觉」变成了「检查两个模型像不像」,没有意义。
这里有个坑放在第十一节:
createExamples是追加语义,脚本重复跑会把 12 条变成 24 条、36 条。评估集被污染,分数就没法比了。
八、Step 4:三个维度,让 LLM 当裁判
rag-demo/src/eval/evaluators.mjs 用 openevals 的 createLLMAsJudge 定义了三个评估器,对应 RAG 三个不同层面的质量问题。
8.1 三个评估器
js
import {
createLLMAsJudge,
RAG_GROUNDEDNESS_PROMPT, // 回答是否有据(幻觉检测)
RAG_HELPFULNESS_PROMPT, // 回答是否有用
RAG_RETRIEVAL_RELEVANCE_PROMPT, // 召回是否相关
} from "openevals";
const judge = new ChatOpenAI({
apiKey: process.env.OPENAI_API_KEY,
configuration: { baseURL: process.env.OPENAI_BASE_URL },
model: process.env.MODEL_NAME ?? "qwen-plus",
temperature: 0,
});
const ragGroundnessJudge = createLLMAsJudge({
prompt: RAG_GROUNDEDNESS_PROMPT,
feedbackKey: "rag_groundness",
judge,
continuous: true,
});
// helpfulness、retrieval_relevance 同理
| 评估器 | 输入 | 在回答什么问题 | 分数低说明 |
|---|---|---|---|
| groundedness | context + answer |
答案里的每句话,上下文能支撑吗? | 模型在编(幻觉),或检索内容不够用 |
| helpfulness | question + answer |
这个回答真的解决了用户的问题吗? | 答非所问、答得太空泛 |
| retrieval_relevance | question + context |
召回的四段文档和问题相关吗? | 检索层坏了,embedding / 切块 / 索引要调 |
三个维度分开看,能直接定位问题出在检索还是生成:
- retrieval relevance 高、groundedness 低 → 召回是对的,模型没用好(提示词或模型问题);
- retrieval relevance 低 → 检索就错了,后面的生成再强也救不回来;
- groundedness 高、helpfulness 低 → 回答「有据但没用」,比如复述了一堆上下文却没回答具体问题。
8.2 为什么可以连续打分
continuous: true 让裁判输出 0 到 1 的连续分数,而不是「对 / 错」两档。二值打分下,一次提示词微调把某条从「勉强算对」推到「答得不错」,分数可能纹丝不动;连续分数能看到这种细小提升,也方便直接算平均分做版本对比。
temperature: 0 是对裁判的基本要求------裁判自己都不稳定,分数就没有意义。
8.3 评估器函数的形状
js
export async function ragGroundnessEvaluator({ outputs }) {
return ragGroundnessJudge({
context: { documents: outputs.context },
outputs: { answer: outputs.answer },
});
}
export async function ragHelpfulnessEvaluator({ inputs, outputs }) {
return ragHelpfulnessJudge({
inputs,
outputs: { answer: outputs.answer },
});
}
export async function ragRetrievalRelevanceEvaluator({ inputs, outputs }) {
return ragRetrievalRelevanceJudge({
inputs,
context: { documents: outputs.context },
});
}
export const ragEvaluators = [
ragGroundnessEvaluator,
ragHelpfulnessEvaluator,
ragRetrievalRelevanceEvaluator,
];
每个评估器接收 { inputs, outputs, referenceOutputs },返回一个带 key、score、comment 的 feedback 对象。inputs 是数据集里的问题,outputs 是刚才 Agent 跑出来的答案和上下文------所以第六节里 ask() 返回 context 才这么重要。
九、Step 5:批量跑,拿结果
rag-demo/src/eval/run_eval.mjs 把 Dataset 喂给 Agent,再把结果交给三个评估器:
js
import { evaluate } from "langsmith/evaluation";
import { ask } from "../rag_agent.mjs";
import { ragEvaluators } from "./evaluators.mjs";
async function runRagAgent(inputs) {
const { answer, context } = await ask(inputs.question);
return {
answer,
context: context.map((d) => d.pageContent), // Document[] -> string[]
};
}
const result = await evaluate(runRagAgent, {
data: "rag-eval-v1",
evaluators: ragEvaluators,
client,
experimentPrefix: `rag-openevals-${process.env.MODEL_NAME ?? "qwen"}`,
maxConcurrency: 2,
});
bash
node src/eval/run_eval.mjs
evaluate 会做四件事:
- 从数据集里逐条取出
inputs; - 调用
runRagAgent得到outputs; - 把
inputs/outputs/referenceOutputs交给每个评估器; - 把整次实验的结果上传到 LangSmith。
9.1 结果在哪看
终端不会打印汇总分数,结果都在 LangSmith 的 Experiments 页面:
| 位置 | 内容 |
|---|---|
| 实验列表 | 每次运行一行,带平均分、样本数、耗时 |
| 单条样例 | 问题、生成答案、标准答案、三个评估器的分数和评语 |
| 对比视图 | 勾选多个实验,逐条比较分数变化 |
experimentPrefix 里带上模型名 是故意的:rag-openevals-qwen-plus、rag-openevals-xxx 会自动成为不同的实验。同一份 12 条数据集,换模型前后各跑一次,在对比视图里直接看三个维度谁升谁降,比拍脑袋靠谱。
9.2 一条有用的优化闭环
拿到分数之后,改什么就有的放矢了:
| 症状 | 先改哪里 |
|---|---|
| retrieval_relevance 低 | 切块大小、embedding 模型、召回 k 值、索引参数 |
| groundedness 低 | 提示词约束、降低 temperature、缩小 chunk |
| helpfulness 低 | 提示词结构、换更强的生成模型 |
改完重跑 run_eval.mjs,用同一份数据集对比------这就是 RAG 的回归测试。 没有它,每次「优化」都只是祈祷。
十、踩坑清单
这些都是写 demo 时实际撞上的,按出现频率排序。
10.1 ?? 救不了 undefined.replace()
milvus_insert.mjs 里这行看起来有兜底,其实没有:
js
const MILVUS_ADDRESS =
process.env.MILVUS_URI.replace(/^https?:\/\//, "") ?? "localhost:19530";
?? 只处理「左边是 null / undefined」的情况,但左边的 process.env.MILVUS_URI 为 undefined 时,.replace() 会先执行并直接抛 TypeError ,根本轮不到 ??。
正确写法:
js
const MILVUS_ADDRESS =
(process.env.MILVUS_URI ?? "http://localhost:19530").replace(/^https?:\/\//, "");
先兜底,再处理字符串。
10.2 同一台 Milvus,两个变量名
写入脚本用 MILVUS_URI,查询用 MILVUS_URL:
js
// milvus_insert.mjs
const MILVUS_ADDRESS = process.env.MILVUS_URI...
// rag_agent.mjs
url: process.env.MILVUS_URL ?? "http://localhost:19530"
只配一个,另一个就会静默回落到 localhost------表现为「明明写入了,检索却一条都没有」。.env 里两个都配上,或者统一成一个变量名。
10.3 baseURL 也分裂成了两个名字
js
// milvus_insert.mjs / evaluators.mjs
baseURL: process.env.OPENAI_BASE_URL
// rag_agent.mjs
baseURL: process.env.OPENAI_API_BASE_URL
同理,少配一个,对应环节就会走默认的 api.openai.com,报 401 或超时。demo 里两个都写进 .env 最省事,正式项目应该统一。
10.4 重复运行 build_dataset.mjs 会污染数据集
readDataset 只判断「数据集在不在」,createExamples 是追加:
js
dataset = await client.readDataset({ datasetName: DATASET_NAME }); // 只读,不查重
const created = await client.createExamples(EXAMPLES.map(...)); // 每次都追加 12 条
跑两次就是 24 条,三次 36 条,平均分被重复样本加权,和之前的实验失去可比性。
要么每次先清空/重建数据集,要么只用 createExamples 传 dataset_id 前先检查样例数量,要么干脆把数据集视为「建一次就不动」的只读资产。
10.5 评估器要 context,runner 就必须返回它
groundedness 和 retrieval_relevance 都读 outputs.context。如果 runner 只返回 answer,这两个评估器会拿不到上下文------分数异常或者直接报错。
而且 context 必须是字符串数组 ,不能是 Document[]:
js
context: context.map((d) => d.pageContent),
10.6 import "dotenv/config" 放在第一行
前面说过,这里再强调一次:langsmith 的 tracer 在模块初始化时读环境变量,dotenv 晚一步,Trace 就静默消失,且没有任何报错。
10.7 Trace 没出现,先查这四项
LANGCHAIN_TRACING_V2=true是否真的被加载(console.log(process.env.LANGCHAIN_TRACING_V2));LANGCHAIN_API_KEY是否有效;LANGCHAIN_PROJECT是否写成了你正在看的项目;- 网络能否访问 LangSmith 端点(国内网络环境偶尔不稳定,可以配
LANGCHAIN_ENDPOINT指向自建/代理地址)。
还有一个容易忽略的点:LangSmith 上报是异步的 。进程退出太快时,最后一条 Trace 可能还没传完;脚本跑完立刻 process.exit() 的话,加一点等待,或者先拿到 await 结果再退出。
10.8 别在终端里 console.log(vectors)
milvus_insert.mjs 里调试用的 console.log(chunks) 和 console.log(vectors) 会打印完整向量数组,一个 1024 维向量就是一屏,几十条直接刷爆终端,还拖慢执行。调试完记得删掉,或者只打印长度:
js
console.log(`chunks: ${chunks.length}, dim: ${vectors[0].length}`);
十一、总结
把整条链路串起来:
- Agent 的「盲盒感」来自不可度量。 调了哪个工具、哪步慢、烧了多少 token------这些问题
console.log回答不了,需要结构化 Trace。 - LangSmith 接入几乎零成本。 配好
LANGCHAIN_TRACING_V2/LANGCHAIN_API_KEY/LANGCHAIN_PROJECT,langchain/langgraph的每一步自动上报,业务代码不动。dotenv记得放第一行。 - 一条 Trace 是一棵树。 chain / llm / tool / retriever / graph 各是一类 Run,逐层记录输入输出、耗时、token、错误;Graph 视图还能把 LangGraph 的实际路径画出来。
- Monitoring 看趋势。 错误率、P50/P99 延迟、token 成本,按项目和时间维度聚合,比单条日志更能反映真实质量。
- RAG 评估要拆两段。 检索质量和生成质量都可能坏,而且坏法不同;用
retrieval_relevance/groundedness/helpfulness三个维度分开打分,才能定位问题在检索层还是生成层。 - Dataset 是考卷,必须固定。 问题 + 标准答案存进 LangSmith,改模型、改提示词都在这份考卷上重跑,分数才有可比性。
- Evaluator 是裁判。
openevals的createLLMAsJudge配好 prompt、feedbackKey、continuous: true,就能把主观的「答得好不好」变成可比较的分数。 evaluate()把闭环跑通。 runner 返回answer+context,结果自动上传成 Experiment;experimentPrefix带上模型名,同一数据集横向对比,优化就有了依据。
最后记一句:
如果你无法度量它,你就无法管理它。
Tracing 让你看见一次执行,Monitoring 让你看见长期趋势,Dataset + Evaluator 让你看见「改动到底有没有用」。三者连起来,Agent 的迭代才从玄学变成工程。