企业官网建设流程全解析

1. 这篇文章真正要解决的问题

如果你最近关注 AI 工程化方向的技术动态，可能已经在社区里看到过 Jason Liu 对某些工具的高度评价。作为在可观测性、LLM 应用开发和 AI Agent 工程实践领域都有深厚积累的技术专家，Jason Liu 的评价在开发者社区里往往有比较强的风向标意义。

但这里要先给一个判断：与其纠结“哪个工具被盛赞”，不如拆解“这个工具到底解决了什么开发痛点”。因为 AI 工具迭代速度极快，今天被盛赞的工具，三个月后可能就被新方案替代。真正值得沉淀的，是这类工具为何能获得一线工程师认可，以及它的设计思路能给我们自己的项目带来什么启发。

从材料看，Jason Liu 盛赞的这款工具，核心价值集中在AI 代理（Agent）开发与调试效率上。如果你正在做 LLM 应用、搭过 Agent 工作流，或者被“模型行为不可控”“调试链路不透明”“测试用例难维护”这些问题折磨过，那这篇文章就是为你准备的。

读完这篇文章，你会得到四个层面的收获：

1. 理解这类工具在 AI 工程链路中的定位，以及它和传统调试工具的本质差异。
2. 掌握它的核心概念，搞清楚“追踪（Tracing）”“评估（Evaluation）”“数据集（Dataset）”这些术语到底在解决什么。
3. 通过一个可落地的示例，亲手跑通“接入工具 → 构建测试用例 → 评估模型输出 → 优化提示词”的完整流程。
4. 避开我在实际工程中最常看到的误区和坑，包括版本兼容、成本控制、测试集设计等。

2. 被盛赞的工具到底在解决什么：AI 工程的可观测性危机

2.1 传统开发调试逻辑在 LLM 应用里失效了

先看一个很典型的场景。

你写了一个传统后端接口，输入参数不对，日志打印出来，一查就能定位。原因很明确：要么是空指针，要么是 SQL 写错，要么是下游服务超时。这类问题有一个共同特征：代码执行路径是确定的，错误是可复现的。

但到了 LLM 应用领域，这个逻辑彻底失效了。同样是“用户输入”，同一个 Prompt，同一个模型，温度调到 0.2 和 0.8，输出可能完全不同。更头疼的是，即使温度设成 0，不同版本的模型、不同的上下文长度、甚至同一次请求中不同的 token 采样，都可能让结果出现肉眼可见的差异。

这意味着什么？意味着你没法再用“看日志、查异常”的方式去定位问题。你根本不知道模型为什么给出了这个回答，是哪一段上下文影响了它的判断，还是它的“幻觉”机制在起作用。

2.2 流程编排让问题更难定位

再叠加一层流程编排。

现在的 AI 应用很少是“一个 Prompt 走天下”，基本都是多步骤的 Agent 工作流：先做意图识别，再调用工具检索知识库，然后把结果拼接成上下文，最后让模型生成回答。任何一个中间节点的输出有问题，都会传导到最终结果。

更麻烦的是，LLM 的“软错误”不像传统代码的“硬错误”那么明显。传统代码错了就是抛异常，但 LLM 应用经常是“能跑通，但结果不对”，或者“能给出答案，但推理链路是错的”。

这种场景下，你需要的不是传统日志，而是一种能够完整还原 LLM 请求链路、记录中间每一步输入输出、并把多个请求关联成测试集进行批量评估的工具。

这就是 Jason Liu 盛赞这类工具的根本原因：它把 AI 应用开发从“盲人摸象”变成了“可视化手术”。

2.3 一个关键概念：LLM 可观测性

你可能听过“可观测性（Observability）”这个词，传统分布式系统里它指的是通过日志、指标、追踪来理解系统状态。但 LLM 可观测性有本质区别：

• 传统可观测性关注“系统是否健康”（延迟、错误率、CPU 使用率）。
• LLM 可观测性关注“模型行为是否符合预期”（推理链路、上下文使用、输出质量）。

这意味着你不能只监控系统指标，还必须监控语义层面的信息。比如：

• 用户这次输入被路由到了哪个意图分类？
• Agent 在检索知识库时是否找到了相关文档？
• 模型最终生成时采用了哪一段上下文？
• 如果输出质量差，是 Prompt 设计问题、检索质量差，还是模型能力不足？

这些问题有一个共同点：它们都需要把请求链路完整记录下来，然后从语义层面进行分析。这正是被盛赞工具的核心设计目标。

3. 核心概念：从一个示例任务说起

在进入实操之前，先把概念讲透。我建议用一个具体的示例来理解整套机制。

假设你要做一个“智能客服助手”：

• 用户输入：“我想查询订单状态”
• 应用流程：识别意图 → 调用订单系统 API → 获取订单信息 → 模型生成回复

这个流程看似简单，实际工程化后会遇到几个典型问题：

问题一：怎么知道每个环节用了多长时间？如果整体响应变慢，是模型推理慢，还是 API 调用慢？没有链路追踪，你只能靠猜。

问题二：怎么知道模型回答得对不对？“你的订单已发货，预计 3 天内到达”这个回答怎么判断对错？“发货状态”是否真的来自订单系统？模型是否编造了物流信息？

问题三：改了 Prompt 之后，怎么确认效果真的变好了？凭感觉测试三五个用例？还是用一个固定测试集跑一遍，量化对比改进前后的得分？

这时候，被盛赞的工具提供了一套完整的解决方案，核心由以下模块组成：

这四块组合起来，就形成了一个完整的工作闭环：

1. 先把应用接入追踪，记录所有线上请求。
2. 从线上请求中筛选出代表性用例，保存为数据集。
3. 在数据集上批量运行评估，找到问题集中的方向。
4. 调整 Prompt 或应用逻辑，再次运行评估，对比分数变化。

现在你可能理解了：这个工具不是单纯“追踪”或“评估”，而是把追踪、数据、评估串成了一条工程流水线。这比单点工具的价值高得多，也是它能获得 Jason Liu 这类技术专家认可的关键原因。

4. 环境准备：在本地把最小闭环跑起来

这部分我们进入实操。要完整演示整个工作闭环，需要一个支持 LLM 应用开发的环境。这里的思路是通用的，你可以替换成自己熟悉的技术栈。

4.1 技术栈选择与版本说明

为了让你能顺利复现，我选择了以下技术栈：

• Python 3.10 及以上版本（当前主流 LLM 应用开发语言）
• OpenAI 兼容 API（你可以使用 OpenAI、或其他兼容 OpenAI 接口的模型服务）
• LangChain 作为 LLM 应用开发框架（用于快速搭建 Agent 工作流）
• 被盛赞的工具本身（下文以“该工具”代指，因为不同生态下同类工具接入方式略有差异）

版本说明：本文不绑定具体版本号，因为相关 SDK 更新非常频繁。建议你在运行以下命令时，以官方最新稳定版本为准。

4.2 安装核心依赖

建议先创建一个独立的 Python 虚拟环境：

python3 -m venv venv source venv/bin/activate

然后安装核心依赖：

pip install openai langchain langchain-openai

如果你要接入该工具的服务端，通常还需要安装对应的 SDK。以当前主流的同类工具为例：

pip install langfuse

如果你的团队用的是另一个类似工具（比如 Helicone、LangSmith），安装方式大同小异，核心都是“安装 SDK → 配置环境变量 → 在框架中设置回调”。

4.3 配置环境变量

在项目根目录创建.env文件：

# 模型服务相关配置 OPENAI_API_KEY=sk-your-api-key OPENAI_BASE_URL=https://api.openai.com/v1 # 该工具服务端配置 LANGFUSE_PUBLIC_KEY=your-public-key LANGFUSE_SECRET_KEY=your-secret-key LANGFUSE_HOST=https://cloud.langfuse.com

需要注意，千万别把密钥提交到 Git 仓库。在.gitignore中加入.env，这是最基本的工程素养。

4.4 验证连接

写一个最简单的测试脚本，确认 SDK 能正常连接：

# 文件路径：test_connection.py from langfuse import Langfuse langfuse = Langfuse() # 创建一个简单的 trace 验证连接 trace = langfuse.trace(name="test-connection") trace.update(output="OK") print("连接成功，Trace ID:", trace.id)

运行：

python test_connection.py

如果终端打印出 Trace ID，说明连接正常，可以进入下一步。

这里要特别说明：如果你用的是本地自托管版本，需要先把服务端跑起来。常见做法是用 Docker 一键启动：

docker run -d --name lf-server \ -p 3000:3000 \ -e NODE_ENV=production \ ghcr.io/langfuse/langfuse:latest

具体命令以你使用的工具官方文档为准。

5. 完整示例：搭建一个带追踪和评估的智能客服

现在进入核心部分。我们搭建一个最小可用的“订单查询 Agent”，并把它接入追踪和评估系统。

5.1 第一步：定义工具函数

我们需要一个简单的“查询订单状态”工具：

# 文件路径：tools.py import json import random def get_order_status(order_id: str) -> str: """模拟查询订单状态""" # 实际项目中这里会调用真实的订单系统 API statuses = ["已发货", "配送中", "已签收", "待发货"] status = random.choice(statuses) return json.dumps({"order_id": order_id, "status": status})

这个函数模拟了真实业务中的 API 调用。在实际项目中，你只需要把函数体替换成真实的 HTTP 请求即可。

5.2 第二步：搭建 Agent 工作流

使用 LangChain 构建一个简单的 Agent 流程：

# 文件路径：agent.py import os from dotenv import load_dotenv from langchain_openai import ChatOpenAI from langchain.agents import AgentExecutor, create_openai_functions_agent from langchain.prompts import ChatPromptTemplate from langchain.tools import Tool from tools import get_order_status load_dotenv() # 初始化 LLM llm = ChatOpenAI( model="gpt-4o-mini", # 以你的模型服务为准 temperature=0.0, ) # 定义工具 tools = [ Tool( name="get_order_status", func=get_order_status, description="根据订单 ID 查询订单的物流状态", ) ] # 定义提示词 prompt = ChatPromptTemplate.from_messages([ ("system", "你是一个电商客服助手。请根据用户的问题，使用工具查询订单状态，" "并用亲切的口吻回复用户。如果用户没有提供订单号，请引导用户提供。"), ("human", "{input}"), ("placeholder", "agent_scratchpad"), ]) # 创建 Agent agent = create_openai_functions_agent( llm=llm, tools=tools, prompt=prompt, ) agent_executor = AgentExecutor( agent=agent, tools=tools, verbose=True, max_iterations=3, )

这里的关键配置是create_openai_functions_agent，它让 LLM 能够自主决定何时调用工具、调用哪个工具、以及如何解读工具返回结果。

5.3 第三步：接入追踪回调

这是被盛赞工具发挥作用的关键一步。我们需要把追踪能力接入 Agent 执行过程：

# 文件路径：agent_with_tracing.py from langfuse.callback import CallbackHandler from agent import agent_executor # 创建 Langfuse 回调处理器 langfuse_handler = CallbackHandler( public_key="your-public-key", secret_key="your-secret-key", host="https://cloud.langfuse.com", ) # 执行 Agent，并传入回调 response = agent_executor.invoke( {"input": "你好，我想查一下订单 10086 的物流状态"}, config={"callbacks": [langfuse_handler]}, ) print(response["output"])

此时，你的每一次 AI 应用调用，都会被完整记录下来。在服务端界面上，你能看到：

• 用户输入原文
• 模型完整推理过程
• 工具调用参数和返回结果
• 每个环节的耗时与 token 消耗

这一步做完，你就拥有了“AI 应用请求的 X 光机”。

5.4 第四步：构建评估数据集

有了追踪能力后，我们下一步要做的是构建评估数据集。

数据集构建有两种方式：

方式一：从线上请求导入

登录服务端控制台，找到刚才产生的 Trace 记录，把有代表性的请求保存到数据集中。这种方式最省力，也最贴近真实业务分布。

方式二：手工构建测试用例

更推荐的方式是把典型用户问题和“期望行为”手动组织成数据集：

# 文件路径：build_dataset.py from langfuse import Langfuse from langfuse.client import Dataset langfuse = Langfuse() # 创建数据集 dataset = langfuse.create_dataset(name="order_query_test", description="订单查询场景测试集") # 添加测试用例 dataset.create_item( input={"input": "你好，我想查一下订单 10086 的物流状态"}, expected_output="要求包含该订单的物流状态信息，并在信息不足时引导用户补充" ) dataset.create_item( input={"input": "我的快递到哪了？"}, expected_output="模型应该询问用户提供订单号，而不是自行猜测" ) dataset.create_item( input={"input": "帮我查一下 12345 号订单"}, expected_output="要求模型调用 get_order_status 工具" )

这里的关键点是：测试用例不应该只写“期望的输出文本”，更要想清楚“期望的行为链路”。因为 LLM 应用评估关注的不只是答案对不对，更关注过程对不对。

5.5 第五步：运行批量评估

数据集构建完成后，在服务端控制台配置评估器（Evaluator），或者通过 SDK 批量运行。

核心代码如下：

# 文件路径：run_evaluation.py from langfuse import Langfuse from agent import agent_executor langfuse = Langfuse() # 获取数据集 dataset = langfuse.get_dataset("order_query_test") # 定义一个评估函数 def evaluate_output(output_text: str, expected: str) -> bool: """简单判断输出是否包含关键信息""" # 实际项目中可以用 LLM 作为裁判，或使用更复杂的规则 keywords = ["订单", "状态", "已发货", "配送中", "签收"] return any(kw in output_text for kw in keywords) # 遍历数据集运行评估 for item in dataset.items: result = agent_executor.invoke(item.input) score = evaluate_output(result["output"], item.expected_output) print(f"用例 {item.id}: 得分 {score}")

这一步的意义在于：把主观的“模型回答得好不好”转化为客观、可量化的分数。当你的 Prompt 改动影响模型行为时，系统会通过分数变化告诉你“变好了还是变差了”。

6. 运行结果与效果验证

6.1 预期输出

运行agent_with_tracing.py后，终端会输出类似内容：

> Entering new AgentExecutor chain... > Invoking: `get_order_status` with `{'order_id': '10086'}` > Order status: {"order_id": "10086", "status": "配送中"} 你好！您的订单 10086 当前正在配送中，请耐心等待，预计很快就能到达。如果您还有其他问题，随时告诉我哦～

同时，在服务端控制台能看到完整的 Trace 详情，包括：

• Trace Name: AgentExecutor 的执行链路
• Spans: 对 LLM 调用和工具调用的分别记录
• Token Count: 输入、输出 token 数
• Latency: 每个节点耗时

6.2 如何判断成功

从三个层面判断：

第一层：功能层面。用户的问题被正确识别，工具被调用，模型返回了包含订单状态的回复。

第二层：可观测层面。在服务端界面能看到完整链路，每步耗时和 token 消耗一目了然。如果响应慢，你可以立刻定位是模型推理慢还是工具调用慢。

第三层：可评估层面。在数据集上运行评估后，你能得到所有测试用例的通过/失败情况。如果在 3 个用例中有一个失败，你能立刻看到失败用例的完整链路，从而判断是 Prompt 问题还是工具调用问题。

6.3 失败排查第一原则

如果运行失败，第一步不要急着改代码，先看服务端界面的 Trace 详情。因为：

• 如果是 API 密钥错误，Trace 里会有 HTTP 401 错误。
• 如果是模型中转服务超时，Trace 里会显示耗时异常。
• 如果是工具调用失败，Trace 里会记录异常堆栈。

你不需要猜，直接看链路数据就知道问题在哪。

7. 常见问题与排查思路

基于我在实际工程中的经验，以及社区中高频出现的问题，整理成下面的排查表：

8. 最佳实践与工程建议

8.1 从追踪开始，而不是从评估开始

很多团队一上来就搭建复杂的评估系统，结果发现测试用例设计不合理、评估指标不清晰，整个系统荒废掉了。

更稳妥的路线是：先接入追踪，跑几天生产流量，看看真实请求长什么样。当你对线上流量模式有感觉之后，再从中挑选代表性用例构建数据集。最后才搭建评估器。

理由很简单：评估的前提是理解问题，而追踪是理解问题的最短路径。

8.2 数据集要覆盖“典型场景”和“边界场景”

好的测试集应该包含三类用例：

• 烤羊肉串用例：业务中最常见的 10 到 20 个请求形态。
• 烤焦用例：用户输入模糊、缺少关键信息、意图不明确的情况。
• 奇葩用例：恶意输入、超长文本、特殊字符、多语言混用。

这三类用例各有用途：常规用例保证基本盘不崩，边界用例暴露模型短板，恶意用例保证安全边界不被突破。

8.3 评估器设计：规则和 LLM-as-Judge 结合

评估器设计没有银弹。最稳妥的做法是分层：

# 文件路径：evaluator.py def hybrid_evaluate(output_text: str, expected: str, trace_data: dict) -> dict: """混合评估器：规则 + LLM 判断""" # 第一层：规则判断（成本低，速度快） rule_score = 0 if "订单" in output_text: rule_score += 0.5 if "状态" in output_text: rule_score += 0.5 # 第二层：如果规则判断不通过，再用 LLM 判断 if rule_score < 1.0: # 这里调用 LLM 进行语义相似度判断 llm_score = judge_with_llm(output_text, expected) return {"rule_score": rule_score, "llm_score": llm_score} return {"rule_score": rule_score, "llm_score": None}

规则评估的好处是成本低、可解释性强，适合做快速过滤。LLM 评估的好处是能理解语义，适合判断“虽然用词不一样，但意思一致”的情况。两者结合，才能在成本和效果之间取得平衡。

8.4 控制成本：采样策略

AI 应用的可观测性也有成本问题。每次请求的 trace 都会消耗 token 和存储资源。对于高流量业务，不需要记录每一个请求，更推荐“全量记录 + 抽样分析”的组合策略：

• 生产环境：全量记录基础信息（耗时、状态码、token 数），抽样记录详细链路（比如 10%）。
• 开发环境：全量记录详细链路，方便调试。

大多数可观测性工具都支持采样配置，建议把采样率做成环境变量，而不是硬编码。

8.5 用数据驱动 Prompt 优化，而不是凭感觉

传统开发里，“这个函数性能不好”可以通过 profiler 定位。但在 LLM 应用开发里，很多团队优化 Prompt 全凭感觉。今天觉得“加一句 system prompt 应该会更好”，明天觉得“few-shot 例子再多几个”。

被盛赞工具揭示了一个新的工作方式：

1. 先在数据集上跑一次评估，拿到基线分数。
2. 修改 Prompt。
3. 在同一个数据集上再次评估。
4. 对比分数变化，判断修改是否有效。

这就把“我觉得改得更好了”变成了“数据表明改得更好了”。这个转变，是 LLM 应用开发走向成熟的分水岭。

9. 总结与后续学习方向

写到这里，这篇文章的核心观点可以收束为三点：

第一，LLM 应用开发最大的痛点不是“模型不够聪明”，而是“过程不可见”。模型输出的质量无法用传统日志体系监控，这时候需要一套专门面向 LLM 链路的可观测性工具，把每一次请求的推理过程和工具调用记录成结构化数据。

第二，追踪、数据集、评估三位一体，才能形成完整闭环。单点工具只能解决局部问题，被 Jason Liu 这类技术专家看中的工具，往往是能把“记录请求、沉淀用例、批量验证”串成工程流水线的方案。

第三，这套工作流最大的价值，是把 AI 应用开发从“玄学”变成了“工程”。你不再需要依赖主观感觉来判断 Prompt 改得好不好，而是用测试集和评估分数来支撑每一个决策。

如果你正在做 LLM 应用开发，建议按下面的路径继续深入：

• 先把追踪能力接进你的项目，记录一周线上请求，看看真实流量长什么样。
• 从线上请求中挑出 20 个代表性用例，构建你的第一个数据集。
• 在数据集上跑一次基线评估，记录当前水平。
• 然后开始迭代：改 Prompt、调参数、加工具，每次改动都用评估分数验证效果。
• 一段时间后，你手里就有了属于自己业务的“模型行为基准库”，团队协作时也能用数据说话，而不是靠争论。

这整套方法论，比任何单一工具都更值得长期投入。工具可以替换，但“观测 → 沉淀 → 评估 → 迭代”的工程闭环不会过时。