企业官网建设流程全解析

1. 从一次线上事故说起：为什么RAG系统需要一台“心电监护仪”

做过RAG应用的人大概都有过这种经历：用户反馈“答非所问”，你打开日志一看，检索回来的文档片段看起来没问题，生成模型也没报错，但最终答案就是不对。你开始逐段排查——是切分粒度太粗？是embedding模型选错了？是rerank阶段把关键文档排到了后面？还是prompt模板里塞了太多无关上下文把模型带偏了？整个排查过程像在黑箱里摸象，全靠猜。

这就是RAG系统最让人头疼的地方：它的链路太长了。一个典型的RAG流程至少包含文档加载、文本切分、向量化、向量存储、检索召回、重排序、上下文组装、LLM生成这七八个环节，每个环节都有自己的一套参数和逻辑。任何一个环节出问题，最终表现都是“答案不对”，但根因可能藏在链路的任何一个角落。

我自己的项目就踩过这个坑。当时做的是一个内部知识库问答系统，测试集上准确率能到85%左右，但上线后用户反馈的bad case越来越多。我花了两天时间逐条分析，最后发现是一个很隐蔽的问题：文档切分时用了固定长度512个token，但有些技术文档的关键结论恰好被切在了两个chunk的交界处，检索时两个chunk都召回了，但rerank阶段只保留了其中一个，导致关键信息丢失。这个问题在测试集上没暴露出来，因为测试集的文档结构比较规整，而线上用户的查询涉及的文档类型更杂。

如果当时有一套全链路的观测工具，我完全可以在几分钟内定位到问题——直接看每个chunk的检索得分、rerank后的排序变化、最终送入LLM的上下文内容，一眼就能看出关键信息在哪个环节被丢掉了。这就是LangSmith这类工具的核心价值：它给RAG系统装上了一台“心电监护仪”，让链路上每个环节的输入输出、耗时、得分都变得可见可查。

这篇文章主要面向正在做RAG应用、或者准备把RAG原型推向生产的开发者。不管你是刚接触LangChain生态的新手，还是已经用LangChain搭过几个demo的老手，只要你的RAG系统开始变得复杂、开始出现难以定位的问题，这套观测方案就值得你花时间了解。我会从整体设计思路讲起，然后拆解核心概念和实操要点，接着给出完整的接入流程和参数配置，最后分享我在实际使用中踩过的坑和排查技巧。内容会涉及一些LangChain和LangSmith的具体API，但不会要求你提前精通这些工具——我会把每个关键步骤的意图和原理都讲清楚。

2. 整体设计思路：为什么选LangSmith做RAG观测

2.1 RAG链路的“黑箱”问题到底出在哪

要理解为什么需要LangSmith，先得搞清楚RAG系统的可观测性挑战到底有哪些。我把它归纳为三个层面。

第一个层面是链路长且异构。RAG不是单一模型调用，而是一条由多个组件串联而成的流水线。检索器可能用的是向量数据库的相似度搜索，reranker可能是一个交叉编码器模型，生成器又是另一个LLM。这些组件的输入输出格式各不相同，有的返回文档列表，有的返回得分矩阵，有的返回自然语言文本。如果没有统一的追踪机制，你很难把一次完整的RAG调用串联起来看。

第二个层面是中间状态不可见。在传统的日志方案里，你通常只能记录每个组件的最终输出。比如检索器返回了5个文档，你记下这5个文档的ID；LLM生成了答案，你记下答案文本。但中间过程呢？检索时每个文档的相似度得分是多少？rerank后排序发生了什么变化？上下文组装时每个文档被截断了多少？这些信息在普通日志里往往缺失，而它们恰恰是定位问题的关键。

第三个层面是评估与调试脱节。很多团队会单独搭建一套评估流水线，用测试集跑准确率、召回率等指标。但评估结果只能告诉你“系统表现不好”，没法告诉你“为什么不好”。你需要在调试时能够回放具体的调用链路，对比不同参数下的中间结果差异，才能找到根因。评估和调试应该是同一套数据上的两个视角，而不是两套独立的系统。

2.2 LangSmith在RAG观测中的角色定位

LangSmith是LangChain生态里的一个观测与评估平台，它的核心能力是自动追踪LangChain应用的调用链路。你不需要在代码里手动埋点，只要在环境变量里配置好API Key，LangChain的每个组件调用都会被自动记录，形成一棵完整的调用树。

对于RAG系统来说，这棵调用树的结构大致是这样的：根节点是一次完整的RAG调用，下面挂着检索器节点、reranker节点、LLM节点等子节点，每个节点都记录了输入、输出、耗时、元数据。你可以在LangSmith的界面上展开任意节点，查看它的详细输入输出，也可以对比不同调用之间的差异。

我选择LangSmith而不是自己搭一套观测系统，主要基于三个考虑。第一是接入成本低，LangChain本身已经内置了对LangSmith的支持，只需要配置几个环境变量就能启用，不需要改业务代码。第二是与LangChain生态深度集成，RAG链路里的Retriever、LLM、PromptTemplate等组件都有专门的追踪适配，记录的元数据比通用日志方案丰富得多。第三是调试和评估一体化，LangSmith不仅能看到单次调用的链路，还能把多次调用组织成数据集，跑批量评估，这对于RAG系统的迭代优化非常关键。

当然，LangSmith也不是没有局限。它目前主要支持LangChain和部分主流框架的集成，如果你用的是完全自研的RAG流水线，接入起来会麻烦一些。另外它的数据存储在云端，对于有数据合规要求的场景需要额外考虑。但对于大多数中小团队和个人开发者来说，LangSmith的投入产出比是很高的。

2.3 观测方案的整体架构

在正式接入之前，我先说一下整体的观测架构设计。这套方案的核心思路是分层追踪、按需采样、评估驱动。

分层追踪的意思是，不是所有调用都需要记录到最细粒度。对于高频的线上请求，可以只记录关键节点的输入输出和耗时；对于调试阶段的调用，可以开启全量追踪，把每个中间状态都记下来。LangSmith支持通过环境变量控制追踪级别，你可以根据场景灵活切换。

按需采样的意思是，线上环境不需要记录每一次调用。RAG系统的调用量可能很大，全量记录既浪费存储也会影响性能。我的做法是设置一个采样率，比如只记录10%的请求，同时对于报错或超时的请求强制记录。这样既能控制成本，又不会漏掉关键问题。

评估驱动的意思是，观测的最终目的是为了优化系统。所以我在设计追踪方案时，会提前想好要收集哪些指标——检索召回率、rerank命中率、生成答案的相关性等——然后在追踪数据的基础上构建评估流水线。LangSmith的数据集功能可以把追踪到的调用保存为测试用例，后续跑评估时直接复用。

3. 核心概念拆解：Run、Trace、Project到底怎么理解

3.1 Run：链路中的最小观测单元

在LangSmith的体系里，Run是最基本的观测单元，代表一次组件调用。比如检索器的一次检索是一个Run，LLM的一次生成也是一个Run。每个Run都包含以下核心字段：

理解Run的关键在于：它不是简单的日志行，而是一个结构化的数据对象。你可以把它想象成医院里的一次检查记录——有检查项目名称、检查时间、检查结果、异常标记。当这些Run按照调用关系组织起来，就形成了完整的链路视图。

3.2 Trace：一次完整调用的全貌

Trace是一次完整调用的所有Run组成的树形结构。在RAG场景里，一次用户提问触发的完整流程就是一个Trace。根Run是RAG链本身，它的子Run包括检索、rerank、生成等环节，每个子Run下面还可能挂着更细粒度的Run。

Trace的价值在于它提供了端到端的视角。你可以看到一次调用中所有环节的耗时分布，快速定位性能瓶颈；可以看到数据在链路中的流转过程，发现信息在哪一步丢失或变形；可以对比不同Trace之间的差异，找出bad case的共同模式。

我举个例子说明Trace怎么用。假设用户反馈某个问题的答案不准确，我在LangSmith里找到对应的Trace，展开后发现检索器返回了3个文档，但reranker只保留了1个，而那个被保留的文档恰好不包含关键信息。再往上看，检索器的query是用户原始问题，但用户问题里有一个专业术语，向量模型对这个术语的表示不够准确，导致真正相关的文档没有被召回。整个排查过程不到5分钟，如果没有Trace，我可能需要半天时间。

3.3 Project：Trace的归类容器

Project是Trace的集合，你可以把它理解为一个文件夹，用来归类同一类应用的调用记录。比如你可以为开发环境建一个Project，为生产环境建另一个Project；或者为不同的RAG应用分别建Project。

Project的实用价值在于隔离和对比。开发环境的Trace不会污染生产环境的记录，不同应用的调用也不会混在一起。更重要的是，你可以在Project级别设置采样率、保留策略等参数，灵活控制观测成本。

在实际使用中，我建议至少建两个Project：一个用于开发调试，开启全量追踪；一个用于线上监控，设置采样率并开启错误强制记录。这样既能保证调试时有足够的数据，又不会让线上观测拖垮系统。

3.4 三者关系与RAG链路的映射

把Run、Trace、Project三个概念串起来看：多个Run组成一个Trace，多个Trace归入一个Project。映射到RAG链路上，就是下面这张关系图（用文字描述）：

一次用户提问触发一个Trace，Trace的根Run是RAG Chain。RAG Chain下面挂着若干子Run：Retriever Run负责检索，Reranker Run负责重排，LLM Run负责生成。每个子Run还可以继续细分，比如Retriever Run下面可以挂Embedding Run和VectorStore Run。所有这些Run的输入输出、耗时、元数据都被记录在Project里，供后续查询和分析。

理解了这套概念模型，后面的接入和调试就有了基础。接下来我会讲具体的接入流程和参数配置。

4. 实操接入：从零配置LangSmith观测

4.1 环境准备与依赖安装

接入LangSmith的第一步是准备好基础环境。你需要一个LangSmith账号，目前它提供免费额度，对于个人开发和小团队来说基本够用。注册完成后，在设置页面生成一个API Key，这个Key后面会用到。

依赖方面，你需要确保LangChain的版本足够新。LangSmith的追踪功能在LangChain 0.1.x之后的版本里比较稳定，我建议用最新稳定版。安装命令如下：

pip install -U langchain langchain-core langsmith

如果你用的是特定的向量数据库或LLM提供商，还需要安装对应的集成包，比如langchain-openai、langchain-chroma等。这些包的版本也要注意兼容性，后面我会讲怎么排查版本冲突。

环境变量配置是接入的关键一步。LangSmith通过环境变量来识别是否启用追踪，你需要设置以下变量：

export LANGCHAIN_TRACING_V2=true export LANGCHAIN_API_KEY=your_api_key_here export LANGCHAIN_PROJECT=your_project_name export LANGCHAIN_ENDPOINT=https://api.smith.langchain.com

这里有几个细节值得说明。LANGCHAIN_TRACING_V2是启用追踪的开关，设为true后LangChain会自动把调用记录发送到LangSmith。LANGCHAIN_PROJECT指定Trace归入哪个Project，如果不设置会默认归入default。LANGCHAIN_ENDPOINT是API地址，一般情况下用默认值即可。

注意：环境变量里的API Key不要硬编码在代码里，也不要在版本控制里提交。建议用.env文件管理，并在.gitignore里排除。

4.2 最小可运行示例：给一个简单RAG链装上追踪

在正式改造你的RAG系统之前，我建议先用一个最小示例验证追踪是否正常工作。下面是一个最简单的RAG链，包含检索和生成两个环节：

import os from langchain_openai import ChatOpenAI, OpenAIEmbeddings from langchain_chroma import Chroma from langchain_core.prompts import ChatPromptTemplate from langchain_core.runnables import RunnablePassthrough from langchain_core.output_parsers import StrOutputParser # 初始化组件 embeddings = OpenAIEmbeddings() vectorstore = Chroma(embedding_function=embeddings, persist_directory="./chroma_db") retriever = vectorstore.as_retriever(search_kwargs={"k": 3}) prompt = ChatPromptTemplate.from_template( "根据以下上下文回答问题：\n\n{context}\n\n问题：{question}" ) llm = ChatOpenAI(model="gpt-4o-mini", temperature=0) # 组装RAG链 def format_docs(docs): return "\n\n".join(doc.page_content for doc in docs) rag_chain = ( {"context": retriever | format_docs, "question": RunnablePassthrough()} | prompt | llm | StrOutputParser() ) # 执行调用 result = rag_chain.invoke("什么是向量数据库？") print(result)

这段代码本身没有做任何LangSmith相关的配置，但因为环境变量已经设置好了，LangChain会自动把这次调用记录到LangSmith。执行完成后，打开LangSmith的Project页面，你应该能看到一条新的Trace，展开后能看到Retriever和LLM两个子Run。

如果看不到Trace，先检查环境变量是否生效。可以在Python里打印os.environ.get("LANGCHAIN_TRACING_V2")确认。另外注意，环境变量需要在Python进程启动前设置好，如果在代码里用os.environ动态设置，要确保在导入LangChain之前完成。

4.3 关键参数配置与采样策略

在生产环境里，全量追踪会带来两个问题：一是存储成本，二是性能开销。LangSmith提供了采样相关的配置，可以帮你控制追踪量。

采样率通过LANGCHAIN_TRACING_SAMPLING_RATE环境变量控制，取值范围是0到1。比如设为0.1表示只记录10%的调用。这个采样是在客户端做的，被采样的调用不会发送到LangSmith，所以能有效降低网络开销和存储成本。

但采样有个问题：如果只记录10%，那出错的调用可能恰好没被记录。LangSmith支持对错误调用强制记录，不过这个需要在代码层面处理。我的做法是在RAG链外面包一层异常捕获，对于报错的调用手动打上标签并强制上报：

from langsmith import traceable @traceable(tags=["production", "rag"]) def rag_with_error_handling(question): try: return rag_chain.invoke(question) except Exception as e: # 错误会被自动记录，并带上异常信息 raise

@traceable装饰器是LangSmith提供的轻量级追踪方式，它可以把任意函数包装成一个Run。加上tags参数后，你可以在LangSmith里按标签筛选Trace，快速找到所有生产环境的调用或所有报错的调用。

除了采样率，还有几个参数值得关注。LANGCHAIN_HIDE_INPUTS和LANGCHAIN_HIDE_OUTPUTS可以控制是否记录输入输出内容，对于涉及敏感数据的场景可以设为true。LANGCHAIN_RUN_NAME可以自定义Run的名称，方便在界面上识别。

4.4 验证追踪数据是否完整

配置完成后，怎么确认追踪数据是完整的？我通常从三个维度检查。

第一是链路完整性。打开一条Trace，看它是否包含了所有预期的子Run。一个完整的RAG Trace应该至少有Retriever Run和LLM Run，如果用了reranker还应该有Reranker Run。如果发现某个环节缺失，可能是该组件没有被LangChain的追踪机制覆盖，需要手动用@traceable包装。

第二是数据字段完整性。展开每个Run，检查inputs和outputs是否有值。有时候Run被记录了，但输入输出是空的，这通常是因为组件的调用方式不标准，LangChain没能自动提取参数。这种情况下需要手动在代码里补充元数据。

第三是时间戳准确性。检查每个Run的start_time和end_time，确保耗时计算合理。如果发现某个Run的耗时异常长，可能是该环节确实慢，也可能是时间戳记录有问题。我遇到过因为系统时钟不同步导致耗时计算为负数的情况，后来统一用LangSmith服务端的时间戳才解决。

5. 核心环节实现：把RAG链路的每个节点都“照”出来

5.1 检索环节的观测要点

检索是RAG链路里最需要观测的环节，因为它是信息入口，检索质量直接决定最终答案的上限。在LangSmith里，Retriever Run会记录以下关键信息：检索query、返回的文档列表、每个文档的相似度得分、检索耗时。

但默认的Retriever Run只记录最终返回的文档，不记录检索过程中的中间状态。比如你用的是向量检索，默认不会记录query的embedding向量；你用的是混合检索，默认不会分别记录向量检索和关键词检索的结果。这些中间状态对于排查检索问题很重要。

我的做法是用@traceable手动包装检索函数，把中间状态作为元数据记录下来：

from langsmith import traceable @traceable(run_type="retriever") def retrieve_with_details(query, retriever, top_k=5): # 记录原始query metadata = {"original_query": query, "top_k": top_k} # 执行检索 docs = retriever.invoke(query) # 记录每个文档的得分 doc_details = [] for i, doc in enumerate(docs): doc_details.append({ "rank": i + 1, "content_preview": doc.page_content[:100], "metadata": doc.metadata, "score": doc.metadata.get("score", None) }) return {"documents": docs, "details": doc_details}

这样在LangSmith里展开Retriever Run时，不仅能看到返回的文档，还能看到每个文档的排名和得分，方便判断检索质量。

5.2 重排序环节的观测要点

Reranker是RAG链路里容易被忽视但影响很大的环节。它的作用是对检索返回的文档重新排序，把最相关的排到前面。如果reranker有问题，可能导致关键文档被排到后面，最终被上下文截断丢掉。

观测reranker的关键是对比重排前后的排序变化。我在实际项目里会记录重排前的文档顺序和重排后的文档顺序，以及每个文档的rerank得分。这样一眼就能看出reranker是否把相关文档排到了前面。

@traceable(run_type="chain", name="rerank") def rerank_documents(query, documents, reranker, top_n=3): # 记录重排前的顺序 before_rerank = [doc.metadata.get("id", i) for i, doc in enumerate(documents)] # 执行重排 reranked = reranker.compress_documents(documents, query) # 记录重排后的顺序 after_rerank = [doc.metadata.get("id", i) for i, doc in enumerate(reranked)] return { "documents": reranked[:top_n], "before_rerank": before_rerank, "after_rerank": after_rerank }

在LangSmith里，你可以直接对比before_rerank和after_rerank两个列表，看看排序变化是否符合预期。如果发现相关文档被排到了后面，可能是reranker模型不适合你的领域数据，或者rerank的输入格式有问题。

5.3 生成环节的观测要点

生成环节的观测重点是上下文质量和prompt效果。在LangSmith里，LLM Run会记录完整的prompt内容和生成的答案。你可以检查prompt里是否包含了检索到的关键信息，是否有无关内容干扰，以及生成的答案是否忠实于上下文。

我通常会关注几个指标：prompt的token数量、上下文中各文档的占比、生成答案的长度、是否有幻觉迹象。这些指标在LangSmith的界面上都能直接看到，不需要额外计算。

对于生成环节的调试，我建议把prompt模板也作为一个Run记录下来。这样你可以看到模板渲染前后的内容，方便排查模板变量替换的问题：

@traceable(run_type="prompt") def build_prompt(template, context, question): return template.format(context=context, question=question)

5.4 用@traceable装饰器补充自定义观测

LangChain的自动追踪覆盖了大部分标准组件，但你的RAG系统里可能有一些自定义逻辑，比如查询改写、文档过滤、答案后处理等。这些环节默认不会被追踪，需要用@traceable装饰器手动包装。

@traceable的用法很灵活，可以装饰函数、类方法，也可以作为上下文管理器使用。几个常用参数：

我一般会给自定义环节加上明确的name和tags，这样在LangSmith里筛选和对比时更方便。比如查询改写环节可以命名为"query_rewrite"，并打上"preprocessing"标签，这样所有预处理环节的Run都能一起筛选出来。

6. 常见问题与排查技巧实录

6.1 追踪数据不显示或显示不全

这是接入LangSmith时最常见的问题。可能的原因和排查方法如下：

我踩过最坑的一个问题是环境变量在Jupyter Notebook里不生效。原因是Notebook启动后再设置环境变量，LangChain已经初始化了，不会重新读取。解决办法是在Notebook的第一个cell里就设置好环境变量，或者用langsmith.Client手动初始化。

6.2 性能开销与采样策略的平衡

开启全量追踪后，RAG系统的响应时间可能会增加10%到30%。这个开销主要来自两方面：一是序列化输入输出数据，二是网络传输到LangSmith服务端。

降低开销的方法有几个。首先是降低采样率，线上环境设到0.05到0.1通常就够用了。其次是精简记录内容，对于长文档，可以只记录前200个字符的预览，而不是全文。第三是异步上报，LangSmith的客户端默认是异步发送的，但如果你的调用频率很高，可以考虑批量上报。

我实测下来，采样率0.1的情况下，性能开销基本可以忽略不计。但要注意，采样率太低会导致bad case难以复现。我的折中方案是：正常请求采样0.1，报错请求强制记录，超时请求也强制记录。这样既控制了成本，又保证了问题可追溯。

6.3 敏感数据过滤与合规处理

RAG系统处理的文档可能包含敏感信息，直接记录到LangSmith会有合规风险。LangSmith提供了几种数据过滤机制。

第一种是环境变量级别的隐藏，设置LANGCHAIN_HIDE_INPUTS=true和LANGCHAIN_HIDE_OUTPUTS=true后，所有Run的输入输出都不会被记录，只保留元数据和耗时。这种方式最彻底，但也会丢失调试所需的关键信息。

第二种是代码级别的脱敏，在把数据传给LangChain之前先做脱敏处理。比如对文档内容做关键词替换，对用户query做匿名化。这种方式灵活但需要额外开发。

第三种是Project级别的隔离，为敏感数据的处理单独建一个Project，设置更严格的保留策略。LangSmith支持按Project配置数据保留时长，可以设置自动删除。

我的建议是至少做到第二种，在数据进入RAG链路之前就完成脱敏。这样即使追踪数据被记录，也不会包含原始敏感信息。

6.4 版本兼容性踩坑记录

LangChain生态的版本迭代很快，LangSmith的追踪功能在不同版本间有过一些行为变化。我遇到过几个典型的兼容性问题。

一个是langchain-core和langchain版本不匹配导致追踪失效。LangSmith的追踪逻辑主要在langchain-core里实现，如果langchain的版本太旧，可能调用的是旧的追踪接口。解决办法是统一升级到最新稳定版，并确保langchain-core的版本与langchain兼容。

另一个是某些第三方集成包没有适配最新的追踪接口。比如某个向量数据库的LangChain集成包，在某个版本里没有正确传递Run的元数据，导致检索结果记录不全。这种情况只能等集成包更新，或者自己用@traceable包装一层。

提示：升级LangChain相关包时，建议先在开发环境验证追踪功能是否正常，再推到生产环境。我一般会跑一个最小RAG示例，确认Trace能正常显示后再升级。

6.5 从Trace到评估：让观测数据产生更大价值

追踪数据的价值不止于单次调试。当积累了一定量的Trace后，你可以把它们组织成数据集，跑批量评估。LangSmith的数据集功能支持从Trace直接创建测试用例，然后对不同的RAG配置跑对比评估。

我的做法是每周从线上Trace里采样一批bad case，人工标注正确答案后加入评估数据集。然后每次调整RAG参数（比如换embedding模型、调rerank阈值）时，都跑一遍评估数据集，看指标变化。这样观测数据就形成了闭环：追踪发现问题，评估验证修复，修复后的Trace又成为新的观测数据。

这个闭环是RAG系统持续优化的核心。没有观测数据，调优就是盲人摸象；有了观测数据，每次调整都有据可依。LangSmith在这中间扮演的角色，就是那个把黑箱变成白箱的“心电监护仪”。

我在实际使用中最大的体会是：不要等到系统出问题才想起观测。在RAG系统设计阶段就把LangSmith接进去，让追踪成为开发流程的一部分。这样你不仅能更快定位问题，还能在问题发生之前就发现潜在的风险点。比如通过观察检索得分的分布，你可以提前发现某些query的检索质量偏低，在用户反馈之前就优化掉。

最后分享一个小技巧：给Trace打上业务标签，比如按用户类型、查询类型、文档来源分类。这样在分析时你可以按标签筛选，快速找到特定场景下的问题模式。标签不用多，三五个关键的就行，但能大幅提升排查效率。