TensorZero UI 前端开发指南基于 React Router 7 的工程规范与 Autopilot 内部功能调试【免费下载链接】tensorzeroTensorZero is an open-source LLMOps platform that unifies an LLM gateway, observability, evaluation, optimization, and experimentation.项目地址: https://gitcode.com/GitHub_Trending/te/tensorzeroTensorZero 是一个开源的 LLMOps 平台将 LLM 网关、可观测性、评测、优化与实验能力统一为一体。本文基于仓库中 ui/AGENTS.md 这一面向开发者的工程指南系统梳理 TensorZero UIWeb 管理界面的技术栈、路由组织方式、日志与数据获取规范、代码质量校验命令并重点讲解仅供内部使用的 Autopilot 功能从环境准备、依赖启动到 E2E 测试的完整调试流程。读完本文你可以快速上手 TensorZero UI 的开发环境理解其前后端路由架构并能在本地搭建起 Autopilot 的联调与测试环境。技术栈与工程结构总览根据 ui/AGENTS.md 的第一条约定TensorZero UI 使用以下技术栈React Router 7负责页面路由与 API 路由的统一管理本项目实际使用 React Router 7 的框架模式Tailwind原子化 CSS 框架用于界面样式Node pnpm包管理与脚本执行环境。从 ui/package.json 可以看到具体的依赖构成核心运行时包括react19、react-router7、react-router/node与react-router/serveUI 组件层使用radix-ui、ariakit/react、react-hook-form、zod、recharts数据请求层使用tanstack/react-query与clickhouse/client同时以 file 依赖形式引用了本地 crate 编译产物tensorzero/tensorzero-node指向 crates/tensorzero-node。开发侧还集成了oxfmt格式化、oxlinteslint静态检查、typescript类型检查、vitest单元测试与playwrightE2E 测试。工程约定里还包含一条被 ui/README.md 再次强调的编码习惯新代码优先使用undefined而不是null唯一允许使用null的场景是与napi-rs兼容它用null表示 Rust 侧的OptionT并且永远不要写出T | undefined | null这样的联合类型。路由体系页面与 API 统一定义在 routes.tsAGENTS.md 明确指出UI 的路由页面与 API统一定义在./app/routes.ts中以仓库根目录为基准即 ui/app/routes.ts。这份文件是理解整个 UI 功能面的最佳入口它通过react-router/dev/routes提供的index、prefix、route三个辅助函数声明全部路由。从源码看路由分为几大类首页与基础页面index指向 ui/app/routes/index.tsx另有 Playgroundroutes/playground/route.tsx、API Keysroutes/api-keys/route.tsx、配置编辑器routes/config/route.tsx与健康检查routes/health/route.tsx。API 路由统一挂在api前缀下例如认证用的api/auth/set_gateway_key、推理与状态查询api/tensorzero/inference、api/tensorzero/status、反馈api/feedback以及数据集、评测、工作流评测等数据接口。注意 API 路由与页面路由共用同一份声明这是 React Router 7 框架模式下前端路由 后端 handler一体化的典型形态。功能模块页面数据集datasets、数据点datapoints、评测evaluations、工作流评测workflow-evaluations注释标明原称 Dynamic Evaluations、Autopilot、可观测性observability含 functions、inferences、episodes、models 四块、优化optimization/supervised-fine-tuning。其中 Autopilot 在路由层面被完整呈现页面路由autopilot下挂有会话列表与sessions/:session_id详情页new在该详情路由中被特殊处理API 路由则提供了会话事件流events/stream、授权events/authorize、问答events/answer-questions、消息events/message、中断actions/interrupt、配置应用config-apply/apply与apply-all、全部批准actions/approve_all等一系列接口对应的实现文件位于 ui/app/routes/api/autopilot 目录下。新增页面或接口时只要遵循这套声明方式在 routes.ts 中登记即可被 React Router 7 识别。日志规范统一使用 ~/utils/loggerAGENTS.md 要求优先使用~/utils/logger导出的logger而不是直接调用console.error、console.warn、console.log、console.debug。该模块的实现位于 ui/app/utils/logger.ts从源码可以看到它提供了几个值得注意的能力分级过滤内部维护debug、info、warn、error四个级别。在浏览器环境默认输出debug级别在服务端则读取TENSORZERO_UI_LOG_LEVEL环境变量非法值会给出告警并回退到info。统一消息格式化通过getErrorMessage把 Error 对象、字符串、普通值统一序列化避免直接打印对象导致的信息丢失非序列化值应作为参数传入。版本前缀日志会自动携带[TensorZero UI ${APP_VERSION}]前缀取编译期__APP_VERSION__或npm_package_version便于在生产日志中定位版本来源。这意味着团队通过统一的 logger 入口既控制了日志噪音又保证了日志格式与级别的可观测性。新代码中如需打印日志应直接引用logger而非裸的console。数据获取优先使用 useFetcher 而非 fetchAGENTS.md 建议在 UI 中优先使用 React Router 的useFetcher而非直接调用fetch并附有官方 API 文档链接。useFetcher是 React Router 7 内置的声明式数据交互 Hook它可以直接调用本应用在routes.ts中注册的 action/loader 而不触发页面导航从而让表单提交、按钮操作与数据加载天然继承 React Router 的加载态、错误处理与并发保护机制避免手写 fetch 时的样板代码与竞态问题。对于需要直连 TensorZero 网关的场景UI 提供了封装好的客户端工具~/utils/get-tensorzero-client.server.ts用于普通推理客户端~/utils/get-autopilot-client.server.ts用于 Autopilot 会话客户端。从 ui/app/utils/get-autopilot-client.server.ts 的实现可以看到客户端通过 ui/app/utils/env.server.ts 中的getEnv()统一读取环境变量API Key 优先取环境变量TENSORZERO_API_KEY走缓存单例否则从 cookie 读取有效 API Key逐请求创建客户端保证安全性与灵活性兼得。环境变量约定env.server.ts 是唯一入口值得补充的是AGENTS.md 虽未逐条列出环境变量但 ui/app/utils/env.server.ts 是项目中唯一允许直接访问process.env的文件它集中管理了以下变量TENSORZERO_GATEWAY_URL必填缺失会在启动时报错TENSORZERO_POSTGRES_URL可选Postgres 连接串TENSORZERO_UI_READ_ONLY置为1时启用只读 UITENSORZERO_API_KEY可选网关 API KeyTENSORZERO_UI_CONFIG_FILE可选指向配置文件的本地路径TENSORZERO_AUTOPILOT_BETA_TOOLS可选Autopilot 测试工具开关TENSORZERO_HEADER_*前缀变量会被自动转换为tensorzero-*请求头例如TENSORZERO_HEADER_BETA_TOOLSvalue→tensorzero-beta-tools: value用于向网关传递 Autopilot 所需的附加头部。同时该文件对旧变量TENSORZERO_UI_CONFIG_PATH、TENSORZERO_UI_DEFAULT_CONFIG2025.12 起弃用与TENSORZERO_CLICKHOUSE_URL弃用给出明确的 deprecation 警告新版 UI 的所有数据库查询都改由网关转发无需再向 UI 容器挂载配置文件。这与 AGENTS.md 中 Autopilot 开发时用TENSORZERO_UI_CONFIG_FILE指定配置文件的用法是一致的。代码质量三道闸format、lint、typecheckAGENTS.md 明确规定修改 UI 代码后必须在ui/目录下依次运行pnpm run format、pnpm run lint、pnpm run typecheck且三个命令必须全部通过。对应的脚本定义在 ui/package.json命令实际执行内容作用pnpm run formatoxfmt **/*.{js,jsx,ts,tsx,css,scss,html,json,yaml,md}用 oxfmt 统一格式化各类源文件与配置文件pnpm run lintoxlint . --fix --deny-warnings eslint . --fix --max-warnings0 --config eslint.config.js --cache先跑 oxlintwarnings 视为错误再跑 eslint修复并零警告通过pnpm run typecheckreact-router typegen tsc先为路由生成类型声明再执行 TypeScript 全量类型检查三者互为补充format 保证风格统一lint 拦截静态问题与潜在错误typecheck 借助react-router typegen让路由路径与参数在编译期即可校验。此外ui/package.json还提供了format:check与lint:check只检查不修改的变体适合 CI 场景单元测试可运行pnpm testvitestE2E 测试则通过pnpm test-e2eplaywright执行。Autopilot 功能内部专用的联调与测试AGENTS.md 用较大篇幅专门介绍Autopilot 功能并强调它是Internal Only该功能依赖一个闭源内部 APIe2e_tests/autopilot/下的测试需要访问私有autopilot仓库外部贡献者无法运行这些测试由 autopilot 仓库通过 repository dispatch 在 CI 中触发。如果你是拥有 autopilot 仓库访问权限的内部贡献者可按以下步骤搭建本地环境。第一步设置 AUTOPILOT_REPO 环境变量将AUTOPILOT_REPO指向本地 autopilot 仓库的检出路径export AUTOPILOT_REPO/path/to/autopilot第二步启动 Autopilot 依赖在$AUTOPILOT_REPO目录下执行或在任意目录下通过-f显式指定其 docker-compose 文件docker compose --profile e2e up -d或docker compose -f $AUTOPILOT_REPO/docker-compose.yml --profile e2e up -d--profile e2e会拉起 Autopilot 联调所需的全部依赖容器含网关等保持常驻即可。第三步以 Autopilot 配置启动 UI 开发服务器在ui/目录下执行TENSORZERO_UI_CONFIG_FILE$AUTOPILOT_REPO/e2e_tests/fixtures/config/tensorzero.toml \ TENSORZERO_GATEWAY_URLhttp://localhost:3040 \ pnpm dev这里TENSORZERO_UI_CONFIG_FILE指向 autopilot 仓库中的测试配置文件tensorzero.tomlTENSORZERO_GATEWAY_URL指向本地启动的网关端口 3040。pnpm dev对应 ui/package.json 中的react-router dev会在本地启动带热更新的开发服务器。从 ui/playwright.config.ts 可以看到非 CI 场景下 Playwright 的webServer也会默认执行pnpm run dev并等待http://localhost:5173就绪因此本地开发与 E2E 测试复用同一套 dev server 流程。第四步运行 Autopilot E2E 测试在ui/目录下运行全部 Autopilot 测试TENSORZERO_UI_CONFIG_FILE$AUTOPILOT_REPO/e2e_tests/fixtures/config/tensorzero.toml \ TENSORZERO_GATEWAY_URLhttp://localhost:3040 \ TENSORZERO_PLAYWRIGHT_INCLUDE_AUTOPILOT1 \ pnpm exec playwright test e2e_tests/autopilot/只运行单个测试文件例如TENSORZERO_UI_CONFIG_FILE$AUTOPILOT_REPO/e2e_tests/fixtures/config/tensorzero.toml \ TENSORZERO_GATEWAY_URLhttp://localhost:3040 \ TENSORZERO_PLAYWRIGHT_INCLUDE_AUTOPILOT1 \ pnpm exec playwright test e2e_tests/autopilot/autopilot.spec.ts关键点在于环境变量TENSORZERO_PLAYWRIGHT_INCLUDE_AUTOPILOT1从 ui/playwright.config.ts 的源码可以看到Autopilot 测试默认被testIgnore: autopilot/**排除只有显式设置该变量后才会取消排除并纳入测试。这也是为什么外部贡献者的普通 E2E 测试如pnpm test-e2e不会触碰这些用例。当前仓库中 ui/e2e_tests/autopilot 目录实际包含以下测试文件可供对照了解覆盖范围autopilot.spec.tsAutopilot 主流程测试config-apply.spec.ts配置应用apply/apply-all相关测试user-questions.spec.ts用户问答answer-questions相关测试topk-visualization.spec.ts与variant-performance-visualization.spec.tsTop-K 与变体性能可视化测试。目录下的辅助模块 ui/e2e_tests/autopilot/helpers.ts 提供了两个值得注意的工具函数deterministicTestAndAttempt与uniqueDatasetName。它们基于测试标题 重试次数生成确定性的数据集名称——注释中明确说明这是 Rust 侧deterministic_test_and_attempt与unique_dataset_name的 Playwright 等价实现目的是保证同一测试每次产生相同名称从而充分利用提示词/模型缓存降低 E2E 测试的推理成本。总结TensorZero UI 的工程规范可以概括为三条主线以 ui/app/routes.ts 为中心的页面与 API 统一路由、以~/utils/logger和useFetcher为代表的统一基础设施、以 format/lint/typecheck 为底线的提交前自检。而 Autopilot 作为内部功能其调试路径围绕AUTOPILOT_REPO、TENSORZERO_UI_CONFIG_FILE、TENSORZERO_GATEWAY_URL、TENSORZERO_PLAYWRIGHT_INCLUDE_AUTOPILOT四个关键配置展开先启动 autopilot 仓库的 docker 依赖再以测试配置启动 UI dev server最后显式放开 Playwright 的测试排除项运行 E2E 用例。对内部贡献者而言这套流程可以完整还原 Autopilot 的本地联调环境对外部贡献者而言理解这份约定也有助于把握 UI 的整体架构并绕开无法运行的内部测试来贡献其余功能。【免费下载链接】tensorzeroTensorZero is an open-source LLMOps platform that unifies an LLM gateway, observability, evaluation, optimization, and experimentation.项目地址: https://gitcode.com/GitHub_Trending/te/tensorzero创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考