12.6 · LLM 跟踪与评估（LLM Tracing and Evaluation）

企业连接器与统一搜索 · 本章是 Onyx DeepWiki 中文译文的独立章节页，保留原始链接、源码锚点、模块标签和章节层级。

项目Onyx 章节12.6 状态全文译文模块测试、发布与运维、模型调用与提供方适配、接口与服务契约、界面与交互

项目要点页2.5 参考项目项目章节目录Onyx DeepWiki 原始章节LLM Tracing and Evaluation 上一章12.5 下一章13

源码线索

.github/pull_request_template.md
.github/workflows/release-devcontainer.yml
.gitignore
backend/ee/onyx/server/tenant_usage_limits.py
backend/onyx/background/celery/tasks/evals/tasks.py
backend/onyx/evals/README.md
backend/onyx/evals/eval.py
backend/onyx/evals/eval_cli.py
backend/onyx/evals/models.py
backend/onyx/evals/provider.py

模块标签

测试、发布与运维
模型调用与提供方适配
接口与服务契约
界面与交互
系统架构

中文译文

LLM 跟踪与评估（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/onyx-dot-app/onyx/12.6-llm-tracing-and-evaluation

翻译时间：2026-05-27T08:44:50.441Z

翻译模型：deepseek-chat

原文字符数：9616

项目：Onyx (onyx)

---

大语言模型（LLM）追踪与评估

大语言模型（LLM）追踪框架

追踪系统允许开发者监控大语言模型（LLM）的输入、输出以及中间步骤（如工具调用）。该系统设计为与提供商无关，通过统一接口支持多个后端。

追踪提供商与设置

追踪功能通过 setup_tracing() 初始化，该函数根据环境变量配置活跃的提供商。目前，系统支持以下提供商：

Braintrust：通过 BRAINTRUST_API_KEY 启用。
Langfuse：通过 add_trace_processor() 机制支持。

该框架会捕获详细的元数据，包括模型配置、Token 使用情况和时间信息。

追踪的数据流

下图展示了大语言模型（LLM）请求如何被拦截并发送到追踪提供商。

大语言模型（LLM）追踪数据流

graph TD
    subgraph "请求生命周期"
        A["handle_stream_message_objects()"] --> B["run_llm_loop()"]
        B --> C["LitellmLLM.call()"]
    end

    subgraph "追踪逻辑"
        C --> D["setup_tracing()"]
        D --> E["追踪处理器"]
        E --> F["BraintrustProvider"]
        E --> G["Langfuse/本地"]
    end

    subgraph "外部可观测性"
        F --> H["Braintrust 仪表盘"]
        G --> I["Langfuse 用户界面"]
    end

来源：backend/onyx/evals/eval.py:16-16、backend/onyx/evals/provider.py:30-30、backend/onyx/llm/multi_llm.py:23-23。

评估系统

Onyx 包含一套专用的评估套件，用于衡量聊天响应的质量和检索的准确性。该套件主要由 eval_cli.py 工具和 onyx.evals 模块驱动。

核心评估逻辑

评估系统使用"临时会话"模式来运行测试，避免污染生产数据库。isolated_ephemeral_session_factory 会创建一个事务，该事务在评估完成后自动回滚。

isolated_ephemeral_session_factory：创建一个绑定到连接的 sessionmaker，该连接会启动一个外部事务，确保数据库中不会残留任何副作用 backend/onyx/evals/eval.py:42-68。
evaluate_tool_assertions：将大语言模型（LLM）实际调用的工具与测试用例中定义的预期工具进行比较 backend/onyx/evals/eval.py:104-146。
ChatFullEvalResult：一个数据模型，用于聚合大语言模型（LLM）的答案、工具调用、引用以及 EvalTimings（总毫秒数、首个 Token 毫秒数等）backend/onyx/evals/models.py:21-21、backend/onyx/evals/eval.py:77-101。

评估命令行界面（`eval_cli.py`）

开发者使用命令行界面（CLI）来运行单次或批量评估。它支持以下功能：

聊天评估：发送一条消息并验证响应和工具使用情况。
多轮评估：模拟对话以测试上下文保持能力。
检索评估：衡量 SearchTool 返回文档的相关性。

来源：backend/onyx/evals/eval.py:1-101、backend/onyx/evals/models.py:1-29。

开发者工具：`ods`（Onyx 开发者脚本）

ods 工具是一个基于 Go 的命令行界面（CLI）（以 Python wheel 形式分发），用于简化开发工作流，包括持续集成（CI）管理和代码提升。

关键维护命令

ods cherry-pick（或 cp）：自动将提交从 main 分支移动到发布分支。它会将拉取请求（PR）编号解析为合并 SHA，处理暂存操作，创建热修复分支，并在 GitHub 上打开带有 cherry-pick 🍒 标签的拉取请求（PR）tools/ods/cmd/cherry-pick.go:33-63。
ods run-ci：为来自复刻（fork）的拉取请求（PR）触发 GitHub Actions。它会获取复刻的分支，将其推送到主仓库的 run-ci/ 分支，并创建一个拉取请求（PR）以触发持续集成（CI）管线 tools/ods/cmd/run-ci.go:24-44。
ods trace：用于与追踪日志交互和调试大语言模型（LLM）调用的工具 tools/ods/cmd/root.go:60-60。
ods backend：使用正确的环境变量和重载设置启动 api_server 或 model_server tools/ods/cmd/backend.go:1-20。

`ods` 架构与代码映射

下图将 ods 命令映射到 Go 代码库中的实现。

ODS 命令架构

graph LR
    subgraph "命令行界面（CLI）接口"
        ODS["ods 可执行文件"]
    end

    subgraph "代码实体空间（Go）"
        ODS --> CP["NewCherryPickCommand()"]
        ODS --> CI["NewRunCICommand()"]
        ODS --> BE["NewBackendCommand()"]

        CP --> GIT["internal/git/git.go"]
        CI --> GIT
        BE --> SHELL["exec.Command('uvicorn')"]
    end

    subgraph "系统操作"
        GIT --> GHC["GitHub CLI (gh)"]
        GIT --> GLO["Git 本地/远程"]
        SHELL --> API["FastAPI (onyx.main:app)"]
    end

来源：tools/ods/cmd/root.go:21-64、tools/ods/cmd/cherry-pick.go:96-115、tools/ods/cmd/run-ci.go:81-110、tools/ods/internal/git/git.go:16-21。

环境管理

ods 通过从 .vscode/.env 加载配置来管理本地开发环境。在首次运行 ods backend 时，它会复制 .vscode/env_template.txt 来初始化环境 tools/ods/README.md:176-184。

命令	主要功能	代码引用
`ods compose`	编排 Docker 容器（开发/多租户）	`tools/ods/cmd/root.go:50-50`
`ods backend api`	运行 `uvicorn onyx.main:app --reload`	`tools/ods/cmd/backend.go:1-20`
`ods cherry-pick`	将提交提升到稳定发布分支	`tools/ods/cmd/cherry-pick.go:33-39`
`ods run-ci`	管理外部贡献者的持续集成（CI）运行	`tools/ods/cmd/run-ci.go:24-29`

来源：tools/ods/README.md:69-105、tools/ods/cmd/root.go:1-64。