> ## Content Index
> Fetch the complete content index at: https://www.hubwiz.com/blog/llms.txt
> Use this file to discover other available public pages before exploring further.

# LLM可观测性：AI系统缺失的环节
- URL: https://www.hubwiz.com/blog/llm-observability-the-missing-layer-in-ai-systems/
- Published: 2026-03-15T07:37:52.000Z
- Updated: 2026-03-15T07:37:52.000Z
- Description: 为已部署LLM应用的开发者而设，希望了解其内部实际运行情况。
- Author: admin
- Tags: LLM, #Import 2026-10-14 14:41

您已部署LLM应用。它在测试中运行正常。用户开始使用它。

两周后，有人提交了一个错误。应用返回了错误答案。

您去检查发生了什么。没有日志，没有发送的提示词记录，没有模型接收到的内容记录，也没有知识库中检索器拉取的哪个块的记录。

**您是在盲目调试。**

这不是一个边缘场景。对于大多数在没有可观测性的情况下部署LLM应用的团队来说，这是默认状态。传统软件日志告诉您发生了一个事件。

**LLM可观测性告诉您模型看到了什么，它被给予了什么，以及它为什么以这种方式做出响应。**

没有它，您自己的应用对您来说是一个黑箱。

## 1、为什么LLM需要不同类型的监控

![无](https://www.hubwiz.com/blog/content/images/2026/03/1-T_0WGplBMtwWt64FZXLGFA-1.jpeg)

**标准应用监控覆盖三个方面：**

- 指标、日志和错误。
- 对于LLMs，这个三元组遗漏了最重要的失败模式。

一个普通的网页服务器要么返回200，要么不返回。一个LLM调用返回200，但仍可能完全错误。

**模型以流畅、自信但错误的文本进行响应。您的错误率显示为零。您的状态页面显示绿色。**

但您的用户得到了错误答案。

**LLM可观测性添加了传统监控所跳过的内容：请求内部的可见性。**

**这意味着跟踪：**

- 发送的提示词，精确地，包括系统消息和注入的上下文
- 检索器获取的文档，以及它们与查询的相似程度
- 模型返回的内容
- 每次调用的令牌数量和成本
- 每个步骤的延迟，而不仅仅是端到端
- 输出是否符合质量标准，通过自动评估器或人工审查

**没有这一点，您无法调试质量。您无法知道提示词更改是有帮助还是有害，除非有基线得分供比较。您无法在成本峰值出现在发票之前捕捉到它。**

## 2、可观测性系统实际跟踪的内容：词汇表

术语在LangSmith、Langfuse和Arize Phoenix中是一致的。只需学习一次。

![无](https://www.hubwiz.com/blog/content/images/2026/03/1-vRTI_RMSDoal8Tc8zBtMBg-1.jpeg)

### 运行

**一个** *运行* **是一个工作单元。一次LLM调用是一次运行。**

- 一次检索步骤是一次运行。
- 一个格式化提示词的函数是一次运行。

如果您在OpenTelemetry或Jaeger等工具中使用过分布式追踪，那么一次运行相当于一个跨度。

\*\*每次运行捕获：\*\*输入、输出、开始时间、结束时间以及您附加的任何元数据。

LangSmith和Langfuse都支持OTLP（开放遥测协议）导出，因此如果您的基础设施已经运行OpenTelemetry，您可以将LLM追踪导入Datadog、Grafana或您现有的可观测性堆栈，而无需添加单独的仪表板。

### 追踪

**一个** *追踪* **是一个用户请求的完整记录。**

它是一系列通过共享追踪ID链接的运行。在RAG应用中，单个追踪包含按顺序的检索运行、提示词构建步骤和LLM调用。

将追踪视为收据。一个请求所发生的一切，按顺序，都在上面。

### 线程

**一个** *线程* **将多轮对话的追踪分组。**

每轮产生自己的追踪，但它们通过共享标识符链接。LangSmith通过在运行的元数据中的特殊元数据键识别这一点：`session_id`、`thread_id`或`conversation_id`。

对于聊天机器人，线程让您能看到完整的对话，而不是单个断开的轮次。

### 项目

**一个** *项目* **是追踪的容器，通常每个应用或环境一个。** 为`rag-production`、`rag-staging`和`rag-dev`设置独立的项目，可以保持监控的清晰，并允许您跨环境比较质量。

### 反馈

***反馈*** **是附加到运行上的分数。** 它可以来自用户（通过API连接的点赞或点踩按钮），来自自动LLM-as-judge评估器，或来自通过注释队列工作的人工审查者。每个反馈条目有一个键，如`user-score`或`groundedness`，以及一个数值或分类值。

反馈是将追踪从被动日志转变为质量测量系统的关键。

### 元数据和标签

**元数据是在调用时附加到运行上的键值对：**

```json
{"llm": "gpt-4o-mini", "user_id": "abc123", "app_version": "2.4", "variant": "B"}

```

标签是用于过滤的平面字符串标签。两者都允许您稍后切片追踪历史：显示版本2.4的所有追踪，或显示用户为user abc123的所有追踪。

记录元数据的成本为零。

**不记录它意味着您无法分组、比较或诊断出现问题时的情况。**

## 3、没有可观测性时LLM应用程序故障的位置

![无](https://www.hubwiz.com/blog/content/images/2026/03/1-wjuFNJYbK8o2zHO4LUEBpQ-1.jpeg)

本节是您应该关注上述所有概念的原因。这些是仅在追踪级别可见的特定故障模式。

**提示词漂移。** 您六周前编辑了一个提示词。 seitdem，一类查询一直返回较低质量的答案。如果没有每次追踪的提示词日志，您就无法知道在降级开始时哪个版本的提示词是活跃的。您正在查看输出，但没有产生它们的输入。

**沉默的检索失败。** 向量搜索可能在不抛出任何错误的情况下返回错误结果。检索器获取与查询共享词汇但不回答它的块。模型读取这些块并产生听起来合理但错误的响应。不会触发异常。您的错误率保持为零。

这就是它的样子。用户问：“LangSmith评估是如何工作的？”

检索器获取：

```yaml
块1：LangChain代理概述
块2：嵌入介绍
块3：通用LLM评估指标

```

这些都不解释LangSmith的实际评估API。模型读取它们并仍然回答。请求返回HTTP 200。没有警报触发。

有追踪存在时，您可以看到确切的块、它们的相似度分数、发送的提示词和输出。您可以在三十秒内知道检索器是问题所在，而不是模型。没有追踪，您只是在猜测。

- **隐藏成本增长。** 令牌数量根据提示词长度、检索到的上下文大小和输出长度而变化。每请求增加200个令牌的提示词更改听起来是次要的。在每日10,000次查询和GPT-4o定价下，这大约是每天10到20美元，或每月300到600美元的额外成本来源于单次编辑。没有按请求记录令牌数量，您会在账单上发现这一点。
- **仅在某些查询类型中出现的延迟。** 所有查询的平均延迟可能看起来很好。但一类查询持续需要8秒。没有追踪中的逐步延迟，您无法确定瓶颈是在检索器、提示词构建还是模型调用。每个都有不同的修复方法。
- **代理循环。** 在代理系统中，如果没有正确触发退出条件，代理可以无限期地循环通过工具调用。请求最终会超时。您的日志显示一个超时错误。它们没有显示在其之前运行的11个工具调用，每个返回了什么，或者哪一步触发了循环。

## 4、从零到生产设置可观测性

两层需要实施：追踪（发生了什么）和评估（是否良好）。

### 环境设置

```typescript
pip install langsmith openai
export LANGSMITH_TRACING=true
export LANGSMITH_API_KEY="your-langsmith-api-key"
export OPENAI_API_KEY="your-openai-api-key"

```

在[smith.langchain.com/settings](https://smith.langchain.com/settings?ref=hubwiz.com)获取您的LangSmith API密钥。除非您将`LANGSMITH_PROJECT`设置为特定名称，否则追踪将进入名为`default`的项目。

### 步骤1：包装LLM客户端

一个导入。一行更改。这是最小可行的开始。

```javascript
from openai import OpenAI
from langsmith.wrappers import wrap_openai
client = wrap_openai(OpenAI())
# 每个client.chat.completions.create()调用现在会自动追踪

```

这会记录每个LLM调用：发送给模型的完整消息列表、响应、模型名称、令牌数量和延迟。目前不需要在其他任何内容上添加装饰器。

### 步骤2：追踪整个流水线

包装客户端捕获了LLM调用，但没有捕获检索步骤或提示词构建。使用`@traceable`来包装整个流水线函数。

```typescript
from openai import OpenAI
from langsmith.wrappers import wrap_openai
from langsmith import traceable

client = wrap_openai(OpenAI())
@traceable
def rag(question: str) -> dict:
    docs = retriever(question)
    system_message = (
        "Answer using only the information below:\n" + "\n".join(docs)
    )
    resp = client.chat.completions.create(
        model="gpt-4.1-mini",
        messages=[
            {"role": "system", "content": system_message},
            {"role": "user", "content": question},
        ],
    )
    return {"answer": resp.choices[0].message.content, "documents": docs}

```

**现在一次追踪显示：** 进来的问题、检索器获取的文档、构建的完整提示词以及模型返回的内容。

**将文档与答案一起返回。** 如果您希望以后运行基于事实性的评估，这是可选的。如果您的函数仅返回字符串，则无法检查答案是否实际上得到检索上下文的支持。

### 步骤3：记录元数据和运行ID

```typescript
from langsmith import traceable, Client
from langsmith import uuid7

ls_client = Client()
@traceable(metadata={"llm": "gpt-4.1-mini", "app_version": "2.4"})
def rag(question: str, user_id: str) -> dict:
    ...

```

对于动态元数据（例如在装饰时 unknown 的用户 ID），使用 `langsmith_extra` 在调用时传递：

```makefile
run_id = str(uuid7())
result = rag(
    question,
    langsmith_extra={
        "run_id": run_id,
        "metadata": {"user_id": user_id}
    }
)

```

存储该 `run_id`。您需要它将用户反馈附加到特定的运行上。

### 步骤4：捕获用户反馈

```bash
ls_client.create_feedback(
    run_id,
    key="user-score",
    score=1.0,   # 1.0 = 点赞，0.0 = 点踩
)

```

将此连接到您的应用程序使用的任何UI反馈机制。即使是二进制的点赞或点踩也能告诉您哪些查询用户认为有用，哪些他们认为没用。一旦有足够的量，这个信号就很有价值。

### 步骤5：将检索器作为其自身的运行分离出来

用`run_type="retriever"`标记检索器，以便LangSmith知道将其视为不同的追踪组件，这使得追踪结构更易于检查。

```ruby
@traceable(run_type="retriever")
def retriever(query: str) -> list[str]:
    # 你的向量搜索逻辑在这里
    return results

```

现在追踪显示检索步骤和LLM步骤作为顶级`rag`追踪下的兄弟运行。您可以独立于模型调用查看检索器的输入、输出和延迟。

### 层2：评估

追踪告诉您发生了什么。评估告诉您是否良好。

**离线评估** 在部署之前运行。构建一个包含20到50个代表性查询和参考答案的数据集，根据它们评分您的流水线，并记录这些基线数量。对提示词、模型或检索策略的每个未来更改都会根据这些基线在发货前进行评估。

**在线评估** 自动对实时生产流量的样本进行评分。在每个请求上运行评估器成本高昂。10%的随机样本足以捕捉质量趋势。对于大多数团队，即使在规模下的5%也是足够的。

**四个值得在RAG应用中跟踪的指标：**

指标 它衡量什么 需要参考答案？ 正确性 答案是否在事实上正确？ 是 基于事实性 是答案得到检索到的文档支持？ 否 答案相关性 答案是否解决了提出的问题？ 否 检索相关性 检索器是否返回了有用的块？ 否

基于事实性和检索相关性不需要策划的参考答案。可以在每个生产请求上运行它们，而无需数据集。

## 5、在生产中实际上重要的事情

一旦您有流量，一些具体的做法将区分那些保持质量领先的团队和那些对用户投诉做出反应的团队。

**抽样评估，不要在所有内容上运行。** LLM-as-judge评估器消耗令牌。10%的随机样本以 fraction 的成本提供统计信号。对于非常高流量的端点，1%通常足以捕捉趋势。

**在每次调用上设置** **`max_tokens`** **。** 未限制的输出长度直接增加成本和延迟。如果您的应用通常需要300个令牌，将上限设置为400或500。修剪响应的成本低于失控输出峰值在规模下的成本。

**使用元数据进行A/B测试。** 测试两个提示词版本？在元数据中用`{"variant": "A"}`或`{"variant": "B"}`标记运行。LangSmith的Monitor选项卡允许您按任何元数据键分组图表，并在实时流量上比较变体的质量得分、延迟和令牌使用情况。

**将检索和生成质量作为独立信号进行跟踪。** 答案质量的下降可能来自检索器或LLM。如果您仅测量最终答案质量，您无法确定是哪一层负责。检索相关性和基于事实性作为独立指标会立即告诉您应该查看哪里。

**在您投入生产之前配置的四个警报：**

- 基于事实性得分低于您的离线基线
- p95延迟超过您的响应时间目标
- 每日令牌成本超过您的预算阈值
- 任何端点上的错误率升高超过2%

**在发布前构建您的评估数据集。** 几乎没人这样做。一旦您上线，时间就会更少，压力更大。在发布前一天，策划20到50个带有预期答案的查询。获得基线得分。每个未来部署都将与这些数字竞争。

**LangSmith在其SaaS层级保留追踪400天。** 对于如提示词漂移或检索新鲜度衰减等缓慢降级的问题，您需要足够的历史来看到趋势。如果追踪包含重要内容，请在其过期前将其添加到数据集中。LangSmith中的数据集会无限期持续。

### 6、决策矩阵：在每个阶段设置什么

![](https://www.hubwiz.com/blog/content/images/2026/03/image-128.png)

**最小可行设置是：** 包装LLM客户端，追踪整个流水线，从您的流水线函数返回结构化输出，按请求记录运行ID，并连接用户反馈。这不到一天的工作，并为您提供调试任何问题所需的可见性。

### 选择工具

四个主要选项不是可以互换的。

**LangSmith** 涵盖完整堆栈：追踪、评估、数据集管理、提示词版本化和一个地方的生产监控。免费增值。适用于任何LLM提供者，而不仅仅是LangChain。如果您想要一个处理完整可观测性生命周期的工具，这对于大多数团队来说是实际的默认选择。

**Langfuse** 是开源的且完全可以自托管。如果您的数据必须停留在您的基础设施内，这是正确的选择。追踪和评估的功能覆盖与LangSmith相近。自己运行需要更多设置，但它赋予您对数据驻留的完全控制权。

**Arize Phoenix** 专为大规模的生产监控和质量漂移检测而构建。更适合进行大规模追踪量的持续统计分析而非每请求调试的团队。开源。

**Helicone** 作为您的LLM API调用前的代理。所需代码更改最少。适合那些首要任务是成本可见性和基本调用记录的团队，在他们进行更深入的可观测性投资之前。

挑选一个。LangSmith或Langfuse是构建RAG或代理应用的大多数团队的正确起点。

## 7、从哪里开始

如果您今天什么都没有准备，顺序很重要。

1. 包装LLM客户端。十分钟的工作。立即让您看到每次模型调用的情况。
2. 在主流水线函数中添加`@traceable`。再十分钟。让您得到完整的请求追踪。
3. 从您的流水线中返回结构化输出。这是进行基于事实性评估所必需的。
4. 记录每个请求的运行ID，并将用户反馈连接到`create_feedback`。这是进行质量跟踪所必需的。
5. 构建您的评估数据集。请在您的下次部署之前完成，而不是之后。

每一步都建立在前一步之上。您不需要一次性完成所有五个步骤，但每一步都比前一步有意义地更好。

原型和生产LLM系统之间的区别不是您选择的模型。而是您在系统出现故障时能否看到系统正在做什么。

## 8、底线

**LLM系统引入了一种新型故障：** 系统似乎健康，而实际上在产生错误答案。

您的仪表板显示零错误。您的API返回200。模型生成流畅文本。一切看起来很好，直到用户指出答案是错误的。

系统健康与答案质量之间的差距是大多数LLM应用挣扎的地方。

可观测性弥合了这一差距。追踪揭示了模型看到了什么上下文，提示词是如何构建的，检索到了哪些文档，以及响应是如何生成的。评估添加了缺失的信号：输出实际上是否良好。

一旦您获得这种可见性，调试就不再是猜测。

构建可靠LLM产品的团队不是那些尝试最多模型的团队。他们是那些能够解释每次请求期间确切发生了什么的团队。

---

原文链接: [LLM Observability: The Missing Layer in Most Production AI Systems ( A Complete Guide ) | by Divy Yadav - Freedium](https://yadavdivy296.medium.com/llm-observability-the-missing-layer-in-most-production-ai-systems-a-complete-guide-09cf8ec90056?ref=hubwiz.com)

汇智网翻译整理，转载请标明出处