agentic_huge_data_base / wiki
页面 Onyx · 12.6 LLM 跟踪与评估·DeepWiki 中文全文译文
DeepWiki 中文译文 / Onyx / 12.6

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

企业连接器与统一搜索 · 聚焦本章的模块关系、源码依据与实现要点。

项目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

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

相关源文件

以下文件为本维基页面的生成提供了上下文：

  • .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
  • backend/onyx/evals/providers/braintrust.py
  • backend/onyx/evals/providers/local.py
  • backend/onyx/llm/prompt_cache/providers/vertex.py
  • backend/onyx/server/tenant_usage_limits.py
  • backend/onyx/server/usage_limits.py
  • backend/tests/external_dependency_unit/answer/stream_test_utils.py
  • backend/tests/external_dependency_unit/answer/test_answer_without_openai.py
  • backend/tests/external_dependency_unit/answer/test_current_datetime_replacement.py
  • backend/tests/external_dependency_unit/answer/test_stream_chat_message.py
  • backend/tests/external_dependency_unit/answer/test_stream_chat_message_objects.py
  • backend/tests/external_dependency_unit/llm/test_llm_provider_called.py
  • backend/tests/external_dependency_unit/llm/test_prompt_caching.py
  • tools/ods/.gitignore
  • tools/ods/README.md
  • tools/ods/cmd/backend.go
  • tools/ods/cmd/cherry-pick.go
  • tools/ods/cmd/desktop.go
  • tools/ods/cmd/install_skill.go
  • tools/ods/cmd/print_latest.go
  • tools/ods/cmd/root.go
  • tools/ods/cmd/run-ci.go
  • tools/ods/cmd/trace.go
  • tools/ods/cmd/web.go
  • tools/ods/go.mod
  • tools/ods/go.sum
  • tools/ods/hatch_build.py
  • tools/ods/internal/_version.py
  • tools/ods/internal/git/git.go
  • tools/ods/internal/git/git_test.go
  • tools/ods/internal/tui/picker.go
  • tools/ods/pyproject.toml
  • widget/src/services/api-service.ts

Onyx 提供了一个强大的框架，用于追踪大语言模型（LLM）交互并评估聊天和检索任务的系统性能。该基础设施支持与 Braintrust 和 Langfuse 等第三方可观测性平台集成，同时还提供了一套命令行评估套件，用于在开发过程中衡量质量改进。

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

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

追踪提供商与设置

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

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

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

追踪的数据流

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

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

Onyx · 追踪的数据流 · 图 1
Onyx · 追踪的数据流 · 图 1

来源：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）来运行单次或批量评估。它支持以下功能：

  1. 聊天评估：发送一条消息并验证响应和工具使用情况。
  2. 多轮评估：模拟对话以测试上下文保持能力。
  3. 检索评估：衡量 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 命令架构

Onyx · ods 架构与代码映射 · 图 2
Onyx · ods 架构与代码映射 · 图 2

来源：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 --reloadtools/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。