# 提示词不能出内网时，如何调试客户的 LLM 应用

> 自托管的 Phoenix 不向 Arize 发送任何数据，追踪定位故障，评测统计频率，但推荐前先读许可证。

原文: https://fdetimes.net/zh/tools/arize-phoenix-llm-tracing-evals-self-hosted/

客户的内部聊天机器人刚刚答错了一个关于退款政策的问题。首先要弄清的是哪一步出了错：检索拉错了文档，模型编造了内容，还是某个工具返回了过期数据。如果看不到一次运行的内部过程，就只能靠猜。

Arize Phoenix 能让你看到这次运行的内部过程。它由 Arize AI 及其社区开发，源代码托管在 GitHub 的 Arize-ai/phoenix。前线部署工程师（FDE）之所以关注它，是因为 Phoenix 可以运行在笔记本电脑上、容器里，或者客户自己的云上。

原因很实际。银行和医院很少同意把提示词和内部文档发给外部 SaaS。根据 Phoenix 的自托管文档，自行托管时 Arize 不会收到任何数据。所有内容都留在客户的基础设施内，即使系统完全断开互联网也是如此。

## 追踪显示哪里出错，评测显示出错多频繁

Phoenix 做两件事。追踪（tracing）把一次运行拆成一连串步骤：模型调用、检索、工具，以及客户团队自己编写的各种逻辑。评测（evals）衡量输出质量，使用的评估器可以基于 LLM、代码或人工标注。

两者要配合使用，因为它们回答的是不同的问题。一条 trace 解释的是某一次具体的失败。评测告诉你这次失败是偶发，还是整个系统的问题，而这正是客户在评审会上想听到的数字。

**要点:** trace 告诉你哪一步出了错；评测告诉你它多常出错。

## 为什么 OpenTelemetry 在客户现场很重要？

Phoenix 基于 OpenTelemetry 构建，通过 OpenInference 插桩采集数据，因此 trace 格式不属于任何一家厂商。OpenInference 是一套扩展 OpenTelemetry 的约定和插件。Phoenix 开箱即支持它，其他后端也可以使用。

对 FDE 来说，这个细节在谈判中很有用。许多客户已经在运行 OpenTelemetry 基础设施，也担心被厂商锁定。你可以直接告诉他们：今天写好的插桩，将来想把 trace 发到别的系统时依然能用。

## 用 Docker 花一个下午

快速试用，一个容器就够了：

```bash
docker run --name phoenix -p 6006:6006 -p 4317:4317 arizephoenix/phoenix:latest
```

6006 端口同时提供 UI 和基于 HTTP 的 OTLP 采集器。4317 端口是基于 gRPC 的 OTLP 采集器。剩下的只是把应用的 exporter 指向其中一个端口。

下面是一个调用 OpenAI SDK 的 Python 应用示意，使用 OpenInference 插桩器和 OpenTelemetry 标准的 OTLP HTTP exporter：

```python
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from openinference.instrumentation.openai import OpenAIInstrumentor

provider = TracerProvider()
provider.add_span_processor(
    BatchSpanProcessor(OTLPSpanExporter(endpoint="http://localhost:6006/v1/traces"))
)
trace.set_tracer_provider(provider)
OpenAIInstrumentor().instrument(tracer_provider=provider)  # 此后每次 LLM 调用都会生成一个 span
```

如果客户网络只允许 gRPC，就换成 OpenTelemetry 的 gRPC exporter，指向 4317 端口。插桩代码不用改。

## 检索坏了，还是模型坏了？

回到那个答错的退款问题。打开 trace，先看检索 span。如果拉回来的分块是去年的政策，问题出在索引，而不是模型。

如果文档是对的，回答却仍然偏离文档，那就是幻觉，要修的是提示词或模型。一个案例不足以下结论，所以下一步是度量。

假设你收集了 20 个退款问题，并用代码写了第一个评估器，只检查每个回答是否引用了来源：

```python
import re

def has_citation(answer: str) -> bool:
    # 回答按约定的 [source: ...] 格式引用了来源即判为通过
    return bool(re.search(r"\[source:[^\]]+\]", answer))
```

假设 20 个中有 14 个通过，6 个失败。第二个评估器用 LLM 判断每个回答是否忠于文档，同时你亲自给这 20 个回答打标签。如果 LLM 只在 12 个上与你一致，先别把它的数字交给客户：先修好评估器的提示词。

## 许可证最容易踩坑

README 称 Phoenix 是“open-source and self-hosted”，但 LICENSE 文件使用的是 Elastic License 2.0。这是源码可用（source-available）许可证，不是 OSI 认可的开源许可证。ELv2 禁止把软件作为托管服务或代管服务提供给第三方。

把两种场景并排放在一起，界限最清楚。下表是针对 FDE 工作对该条款的一种解读，不能替代法律意见：

| 场景 | 按 ELv2 条款的解读 |
|---|---|
| 把 Phoenix 安装在客户自己的基础设施中，由客户团队自己查看 trace 和评测 | 这不属于把软件作为服务提供给第三方，因此风险较低 |
| 咨询公司运行一个共享的 Phoenix 实例，向多个客户出售访问权限 | 直接触碰“不得作为托管或代管服务提供”的禁令 |

起草工作说明书（SOW）时，写清楚 Phoenix 运行在谁的基础设施中、由谁使用。签字前再请法务确认边界。

## 从笔记本电脑到生产环境

Arize 表示自托管版本免费，且没有功能限制。公司另外销售一款名为 Arize AX 的托管产品。客户问为什么不用托管版时，答案通常在于“数据不得离开内网”这一要求。

Docker 文档里有两条值得记住的提醒。Postgres 方面，Phoenix 官方只支持 14 及以上版本，所以第一次会议就要问清客户的数据库版本。在生产环境中要固定镜像版本，不要用 `latest`，以免下一次升级悄悄弄坏线上看板。

## 在项目中引入 Phoenix 的常见错误

最常见的错误是直接相信 LLM 裁判给出的数字。基于 LLM 的评估器只有在和人工标注对比过之后才有价值；如果像上面的例子那样，它在 20 个问题中只有 12 个与你一致，那么它报告的“忠于文档”比例还不能放进幻灯片。

第二个错误是把 `docker run ... :latest` 命令从笔记本电脑原样搬进生产环境。试用时没问题，但文档建议固定你打算使用的确切版本。与之相关的疏忽是忘了检查 Postgres：低于 14 的数据库不在官方支持范围内。

第三个错误出在合同而不是代码：以为 README 里写了“open-source”就够了，然后规划一个供多个客户共用的 Phoenix 实例。写 SOW 之前读一遍 LICENSE 文件，远比签字之后再改 SOW 省事。

## 先学什么？

先学 OpenTelemetry 的概念，再学 Phoenix 的 UI：trace、span、OTLP，以及 HTTP 和 gRPC 的区别。这些知识适用于任何后端。然后练习写评估器，因为最难的部分是界定对客户业务而言什么才算“正确”的回答。

阅读 FDE 岗位描述时，留意 observability、evals、tracing 这类词。简历上写一句“在客户的物理隔离 VPC 内，用 OpenTelemetry/OpenInference 为 LLM 应用搭建追踪，持续跟踪有来源依据的回答比例”，远比罗列一串工具名有分量。

每个 LLM 应用迟早都会答错。客户信任的，是能在客户允许的基础设施内指出哪一步出错、并给出实测数字的人。

**本周动手试试:**

- 在笔记本电脑上用 Docker 运行 Phoenix，把一个小型 RAG 应用的 trace 发到 6006 端口，然后打开 UI，从头到尾读完一条 trace。
- 为同一组 20 个问题写两个评估器：一个用代码（回答是否引用了来源？），一个用 LLM（回答是否忠于文档？），再把两者都和你自己打的标签对比。
- 阅读 Arize-ai/phoenix 仓库中的 LICENSE 文件，写一小段话，说明你的团队为客户部署 Phoenix 时可以做什么、不可以做什么。

## 信源

- [What is Arize Phoenix?](https://arize.com/docs/phoenix)

- [GitHub - Arize-ai/phoenix](https://github.com/Arize-ai/phoenix)

- [Phoenix LICENSE (Elastic License 2.0)](https://github.com/Arize-ai/phoenix/blob/main/LICENSE)

- [Self-Hosting - Phoenix documentation](https://arize.com/docs/phoenix/self-hosting)

- [Docker - Phoenix documentation](https://www.arize.com/docs/phoenix/self-hosting/deployment-options/docker)

- [GitHub - Arize-ai/openinference](https://github.com/Arize-ai/openinference)
