LangSmith 全链路观测:从 Agent 调试到 RAG 量化评估

用 LangChain / LangGraph 写 Agent,最难受的是那种「盲盒感」------它到底调用了哪个工具?每一步耗时多少?流式输出烧了多少 Token?错了是错在检索、错在提示词,还是错在模型?

如果你无法度量它,你就无法管理它。

这篇用两个能直接跑的 demo,把 LangSmith 从「看一条 Trace」一路讲到「拿 LLM 当裁判,批量给 RAG 打分」:调试靠 Tracing,上线靠 Monitoring,优化靠 Dataset + Evaluator。


一、为什么 Agent 需要一块「仪表盘」

LangChain / LangGraph 把 Agent 的编排变得很轻:声明状态、写节点、连边、invoke(),一个能调工具的 Agent 就跑起来了。

但跑起来之后,你很快会陷入三个问题:

  1. 它刚才到底做了什么? 调了 search_docs 还是 refund?参数是什么?返回了什么?
  2. 慢在哪一步? 整体 8 秒,是检索 1 秒、模型 7 秒,还是工具重试了三次?
  3. 贵在哪一步? 一次请求消耗了多少 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 的结构大致是这样:

graph TD A[LangGraph / graph.invoke] --> B[step_ok] A --> C[step_throw ❌ Error] C --> D[Error: DemoError:节点内故意跑错]

每一层都记录了:

字段 内容
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 的链路有两段,两段都可能坏,而且坏的方式完全不同:

graph LR Q[用户问题] --> R[Retriever 检索] R --> C[Context 上下文] C --> L[LLM 生成] L --> A[回答]
出问题的地方 表现 光看 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();
graph LR S([START]) --> R[retrieve 检索] R --> G[generate 生成] G --> E([END])

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 会做四件事:

  1. 从数据集里逐条取出 inputs;
  2. 调用 runRagAgent 得到 outputs;
  3. 把 inputs / outputs / referenceOutputs 交给每个评估器;
  4. 把整次实验的结果上传到 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 没出现,先查这四项

  1. LANGCHAIN_TRACING_V2=true 是否真的被加载(console.log(process.env.LANGCHAIN_TRACING_V2));
  2. LANGCHAIN_API_KEY 是否有效;
  3. LANGCHAIN_PROJECT 是否写成了你正在看的项目;
  4. 网络能否访问 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}`);

十一、总结

把整条链路串起来:

  1. Agent 的「盲盒感」来自不可度量。 调了哪个工具、哪步慢、烧了多少 token------这些问题 console.log 回答不了,需要结构化 Trace。
  2. LangSmith 接入几乎零成本。 配好 LANGCHAIN_TRACING_V2 / LANGCHAIN_API_KEY / LANGCHAIN_PROJECT,langchain / langgraph 的每一步自动上报,业务代码不动。dotenv 记得放第一行。
  3. 一条 Trace 是一棵树。 chain / llm / tool / retriever / graph 各是一类 Run,逐层记录输入输出、耗时、token、错误;Graph 视图还能把 LangGraph 的实际路径画出来。
  4. Monitoring 看趋势。 错误率、P50/P99 延迟、token 成本,按项目和时间维度聚合,比单条日志更能反映真实质量。
  5. RAG 评估要拆两段。 检索质量和生成质量都可能坏,而且坏法不同;用 retrieval_relevance / groundedness / helpfulness 三个维度分开打分,才能定位问题在检索层还是生成层。
  6. Dataset 是考卷,必须固定。 问题 + 标准答案存进 LangSmith,改模型、改提示词都在这份考卷上重跑,分数才有可比性。
  7. Evaluator 是裁判。 openevals 的 createLLMAsJudge 配好 prompt、feedbackKey、continuous: true,就能把主观的「答得好不好」变成可比较的分数。
  8. evaluate() 把闭环跑通。 runner 返回 answer + context,结果自动上传成 Experiment;experimentPrefix 带上模型名,同一数据集横向对比,优化就有了依据。

最后记一句:

如果你无法度量它,你就无法管理它。

Tracing 让你看见一次执行,Monitoring 让你看见长期趋势,Dataset + Evaluator 让你看见「改动到底有没有用」。三者连起来,Agent 的迭代才从玄学变成工程。

相关推荐
NoteDeep 深度笔记4 小时前
DOM 被改乱了怎么办?Notedeep 编辑器的 normalize 设计
前端·javascript·编辑器
翼帆5 小时前
我用 AI 复刻了 CodeTank,重温代码坦克
前端·javascript·开源·ai编程·游戏开发·codetank
黑土豆6 小时前
用 drawink 给业务页面加一层画板:从网页批注到无限板书
前端·javascript·github
Hilaku1 天前
Claude Code 过夜跑长任务实战:tmux、权限、验收,以及我为什么换到 ApexOne
前端·javascript·程序员
程序员大阳1 天前
副队长ES6+教程(14)--手写Promise来加深理解
前端·javascript·es6·源码·promise·手写·深层
程序员大阳1 天前
副队长ES6+教程(11)--生成器 Generator
javascript·es6·生成器·generator
FungLeo1 天前
成为全栈·Vue 管理后台篇·可折叠侧栏与移动抽屉:后台导航的响应式实现
前端·javascript·vue.js·侧边栏·响应式布局·无障碍·移动端导航
程序员大阳1 天前
副队长ES6+教程(9)--Set 与 Map
javascript·es6·set·map·for of遍历
FungLeo1 天前
成为全栈·Vue 管理后台篇·Biome、类型检查、构建和API 代理如何组成质量门禁
前端·javascript·vue.js·typescript·vite·前端工程化·biome