TensorZero UI 前端开发与贡献指南技术栈、编码规范与 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 的 Web 控制台ui/目录为部署提供可观测性Observability、优化Optimization、数据集管理、评估等可视化能力。本文以 ui/CLAUDE.md 引用的 ui/AGENTS.md 为核心结合仓库源码系统讲解 TensorZero UI 的技术栈、路由组织、编码规范、质量门禁以及 Autopilot 这一内部功能的本地开发与端到端测试流程。读完后你将掌握在ui/目录下进行日常开发、自检与提交的全套实操方法并理解 UI 如何与 TensorZero Gateway 通信。技术栈与项目结构React Router 7 Tailwind Node pnpmui/CLAUDE.md的全部内容即一行AGENTS.md指向同目录下的 ui/AGENTS.md其中明确规定了 UI 的技术栈React Router 7页面与 API 路由的框架包管理统一使用pnpmTailwind样式方案配合tailwindcssv4 与tailwindcss/vite插件使用Node运行时与构建工具链基础。在 ui/package.json 中可以验证这套栈的具体版本与脚本react-router/react-router/dev为^7.12.0tailwindcss为^4.1.11react为^19.2.1并依赖tensorzero/tensorzero-nodefile:../crates/tensorzero-node作为本地 Rust 扩展绑定。路由全部集中在 routes.tsUI 路由页面与 API统一定义在 ui/app/routes.ts采用 React Router 7 的index/route/prefixAPI 声明式组织主要包括API 路由/api前缀网关密钥设置、inference/episode 预览、数据集计数、评估运行搜索与取消、反馈提交以及 Autopilot 的 session 事件流、中断、配置应用等接口数据集Datasets列表、Builder、按名称查看数据集与 datapoint评估Evaluations与Workflow Evaluations运行列表与结果页Autopilotsession 列表与会话详情页Playground/playground可观测性Observabilityfunctions、inferences、episodes、models 四个子模块其他监督微调Supervised Fine-Tuning、API Keys、配置编辑器Config、健康检查Health。新增页面或 API 时应当同步修改该文件并在app/routes/下按约定路径如$param动态段添加对应模块。编码规范logger、useFetcher 与类型约定统一使用logger而非 console规范要求优先使用~/utils/logger导出的logger而不是直接调用console.error、console.warn、console.log、console.debug。从 ui/app/utils/logger.ts 的实现可以看到原因logger 封装了日志级别控制debug/info/warn/error服务端通过环境变量TENSORZERO_UI_LOG_LEVEL调整级别默认info浏览器端默认debug并在消息前自动附加[TensorZero UI 版本]前缀便于在分布式日志中定位来源。优先useFetcher而非直接fetch规范要求优先使用 React Router 的useFetcher发起数据变更请求而不是直接调用fetch。useFetcher与 React Router 的 action/loader 体系集成能够自动处理加载状态、错误与并发避免在组件内手写请求生命周期管理。undefined优先于nullui/README.md 补充了一条贯穿全项目的类型约定新代码一律优先使用undefined而非null唯一的例外是napi-rs兼容场景napi-rs 用null表示OptionT并且永远不要写出T | undefined | null这种联合类型。质量门禁改完代码必须通过的三条命令修改 UI 代码后必须从ui/目录运行以下三条命令且全部通过对应 ui/package.json 中的 scriptspnpm run format pnpm run lint pnpm run typecheckformat使用oxfmt对**/*.{js,jsx,ts,tsx,css,scss,html,json,yaml,md}进行格式化lint先跑oxlint . --fix --deny-warnings再跑eslint . --fix --max-warnings0即警告也会导致失败保证零告警提交typecheckreact-router typegen tsc先生成路由类型再执行 TypeScript 全量类型检查。这套门禁同时提供了只检查不改动的format:check与lint:check变体适合 CI 环境使用参见 ui/package.json。Autopilot 功能仅限内部贡献者的本地开发与 E2E 测试Autopilot 是 TensorZero 的一项实验性功能其 E2E 测试位于 ui/e2e_tests/autopilot/。ui/AGENTS.md特别声明该功能依赖闭源的内部 API外部贡献者无法运行这些测试CI 中通过仓库 dispatchrepository dispatch从 autopilot 私有仓库触发执行。从 ui/app/routes.ts 可看到其路由入口/autopilot下的 sessions 列表与详情页相关的 API 路由覆盖事件流、中断、批量批准与配置应用等能力。设置 AUTOPILOT_REPO 环境变量内部贡献者需要先将本地 autopilot 仓库检出路径导出为环境变量export AUTOPILOT_REPO/path/to/autopilot后续的配置、测试命令都会引用$AUTOPILOT_REPO。启动 Autopilot 依赖服务使用 docker compose 启动带e2eprofile 的依赖服务命令可在$AUTOPILOT_REPO目录下直接运行或通过-f显式指定 compose 文件docker compose --profile e2e up -d或docker compose -f $AUTOPILOT_REPO/docker-compose.yml --profile e2e up -d以 Autopilot 配置启动 UI 开发服务器从ui/目录启动开发服务器时需要同时注入两个关键环境变量TENSORZERO_UI_CONFIG_FILE$AUTOPILOT_REPO/e2e_tests/fixtures/config/tensorzero.toml \ TENSORZERO_GATEWAY_URLhttp://localhost:3040 \ pnpm devTENSORZERO_UI_CONFIG_FILE指向 TensorZero 配置文件。从源码看它不只是供 UI 读取还决定配置写入config apply能力是否开启——apply.route.ts 与 apply-all.route.ts 中未设置该变量时接口会直接返回 Config writing is not enabledsession 详情页 也据此控制 UI 开关TENSORZERO_GATEWAY_URL指向本地 Gateway此处为http://localhost:3040。UI 的所有推理、事件流请求都经由此地址代理到 Gateway例如 Autopilot 的 SSE 事件流就是由 stream.route.ts 将/internal/autopilot/v1/sessions/:id/events/stream转发给 Gateway并透传Authorization: Bearer key头。运行 Autopilot E2E 测试在ui/目录下额外设置TENSORZERO_PLAYWRIGHT_INCLUDE_AUTOPILOT1即可让 Playwright 包含 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/该开关的作用可从 ui/playwright.config.ts 得到印证testIgnore默认排除autopilot/**只有在设置了TENSORZERO_PLAYWRIGHT_INCLUDE_AUTOPILOT时才取消排除——这也解释了为什么外部贡献者运行时这些测试不会干扰普通 E2E 套件。仓库还提供了便捷脚本pnpm run test-e2e-autopilot见 ui/package.json。运行单个测试文件同样简单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其他 Playwright 环境变量从 ui/playwright.config.ts 可以看到配套的环境变量约定便于在 CI 或容器中运行TENSORZERO_PLAYWRIGHT_NO_WEBSERVER/TENSORZERO_CI跳过内置 webServer 启动CI 中使用 docker-compose 自行拉起 UI并将 baseURL 切换为http://0.0.0.0:4000TENSORZERO_PLAYWRIGHT_BASE_URL显式覆盖 baseURL如 CI 中的http://ui:4000TENSORZERO_PLAYWRIGHT_RETRIES自定义失败重试次数CI 下默认重试 2 次CI 下forbidOnly: true会阻止带有test.only的代码合入。开发中的实用注意事项离线测试优化工作流当没有真实 Provider API 时可启动仓库的mock-provider-api并在运行 Gateway 时设置TENSORZERO_INTERNAL_MOCK_PROVIDER_APIhttp://localhost:3030见 ui/README.md优化与可观测性依赖UI 的部分页面如推理历史、评估运行依赖 ClickHouse 等存储完整的本地体验可参考 ui/fixtures/docker-compose.yml 与 ui/README.md 的部署说明通用测试脚本pnpm run test运行 vitest 单元测试pnpm run test-e2e运行全部 Playwright 测试默认排除 autopilotpnpm run test-e2e-fast跳过带slow标记的用例以加速迭代见 ui/package.json。小结TensorZero UI 的开发约定高度工程化技术栈统一为 React Router 7 Tailwind Node pnpm路由集中管理于 ui/app/routes.ts编码上要求使用logger与useFetcher并坚持undefined优先任何改动都必须通过format/lint/typecheck三重门禁。对于内部贡献者Autopilot 的本地联调链路AUTOPILOT_REPO docker compose e2e profile TENSORZERO_UI_CONFIG_FILE/TENSORZERO_GATEWAY_URL/TENSORZERO_PLAYWRIGHT_INCLUDE_AUTOPILOT既完整又可控相关环境变量在 ui/playwright.config.ts 与各 API route 源码中均有明确实现依据可直接照此搭建开发环境。【免费下载链接】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），仅供参考