TensorZero UI 路由体系解析routes.ts单一入口、URL 连字符/下划线命名规范与前后端路由协同【免费下载链接】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 平台的控制台UI基于 React Router v7 构建所有前端页面路由与浏览器可直接访问的 API 资源路由统一收敛在 ui/app/routes.ts 一个文件中。本文以 ui/app/routes/README.md 为核心结合 crates/gateway/src/routes/external.rs 与 crates/gateway/src/routes/internal.rs 的 Axum 路由源码完整讲解 TensorZero UI 的 URL 命名规范前端连字符、后端下划线、页面路由/API 路由/网关路由三层体系以及从浏览器 URL 到 Gateway 后端接口的完整调用链帮你快速定位任意页面对应哪个路由文件、如何新增路由。路由定义单一入口routes.tsTensorZero UI 的路由不做目录扫描、不依赖文件系统约定路由而是遵循 React Router v7 的显式配置方式所有路由集中在 ui/app/routes.ts 中通过index、route、prefix三个 API 组合声明最终以RouteConfig导出由 ui/vite.config.ts 中的reactRouter()插件加载。// ui/app/routes.ts节选展示三种基本用法 import { type RouteConfig, index, prefix, route, } from react-router/dev/routes; export default [ index(routes/index.tsx), // API 资源路由统一挂在 api 前缀下 ...prefix(api, [ route(inferences/count, routes/api/inferences/count.route.ts), // ... ]), // 页面路由支持嵌套 layout route(datasets, routes/datasets/layout.tsx, [ index(routes/datasets/route.tsx), route(builder, routes/datasets/builder/route.tsx), route(:dataset_name, routes/datasets/$dataset_name/layout.tsx, [ index(routes/datasets/$dataset_name/route.tsx), ]), ]), ] satisfies RouteConfig;这套配置表本身就是路由即文档的最佳实践ui/app/routes.ts同时承担了 URL 路由表与文件路径索引两种职责每一条route(path, file)都明确写出了用户可见 URL 与对应实现文件的位置。例如route(api-keys, routes/api-keys/route.tsx)表明页面/api-keys由 ui/app/routes/api-keys/route.tsx 渲染。核心规范前端 URL 用连字符后端 API 用下划线ui/app/routes/README.md 中定义了 TensorZero 全仓库必须遵守的 URL 命名约定这是本文的核心路由类型分隔符示例前端页面路由用户可见 URL连字符-/api-keys、/workflow-evaluations、/supervised-fine-tuningRR7 API 路由React Router 资源路由下划线_/api/workflow_evaluations/search_runsGateway API 路由下划线_/internal/workflow_evaluations、/api/curated_inferences该规范的理由在 README 中写得很明确前端 URL 遵循 Web 标准习惯使用连字符SEO 友好、符合用户直觉后端路由使用下划线以与 TensorZero Gateway API 保持一致。在 ui/app/routes.ts 中可以完整验证这两套约定并行存在连字符页面路由/api-keys、/datapoints/new、/workflow-evaluations、/supervised-fine-tuning、/observability/functions、/playground、/config、/health等下划线资源路由/api/workflow_evaluations/search_runs、/api/evaluations/search_runs、/api/datasets/counts、/api/curated_inferences/count等。三层路由体系全览从代码结构看TensorZero UI 与 Gateway 之间存在三层路由理解它们的分工是定位问题的基础。第一层前端页面路由连字符页面路由负责渲染用户界面全部使用连字符命名。完整清单如下均定义于 ui/app/routes.tsURL实现文件功能/ui/app/routes/index.tsx首页/datasets、/datasets/builder、/datasets/:dataset_name、/datasets/:dataset_name/datapoint/:idui/app/routes/datasets/数据集列表、构建器、单数据集详情与数据点详情/datapoints/newui/app/routes/datapoints/new/route.tsx新建数据点/evaluations、/evaluations/runs、/evaluations/results/:datapoint_idui/app/routes/evaluations/评估任务列表、运行记录与结果页/workflow-evaluations、/workflow-evaluations/runs/:run_id、/workflow-evaluations/projects/:project_nameui/app/routes/workflow-evaluations/工作流评估前身是动态评估/autopilot、/autopilot/sessions、/autopilot/sessions/:session_idui/app/routes/autopilot/Autopilot 会话列表与会话详情/playgroundui/app/routes/playground/route.tsx模型实验场/observability/functions、/observability/inferences、/observability/episodes、/observability/modelsui/app/routes/observability/可观测性函数、推理、Episode、模型统计/optimization/supervised-fine-tuning/:job_id?ui/app/routes/optimization/supervised-fine-tuning/route.tsx监督微调job_id可选/api-keysui/app/routes/api-keys/route.tsxAPI 密钥管理/configui/app/routes/config/route.tsx配置编辑器/healthui/app/routes/health/route.tsx健康检查页注意两个细节其一/datasets、/workflow-evaluations、/autopilot、/observability/*、/evaluations都通过layout.tsxindex()的方式实现嵌套布局outlet 子路由文件组织结构与 URL 层级一一对应其二/optimization/supervised-fine-tuning/:job_id?中?后缀表示该动态段可选——同一个路由文件同时处理有 job_id 和无 job_id 两种 URL。第二层RR7 API 资源路由下划线React Router 的资源路由resource route不渲染页面而是作为服务端SSR/loader接口存在供前端页面通过useFetcher或fetch调用。它们统一挂在api前缀下并使用下划线命名与 Gateway 的下划线风格保持血缘关系URL实现文件用途/api/auth/set_gateway_keyui/app/routes/api/auth/set_gateway_key.route.ts设置 Gateway 密钥/api/curated_inferences/countui/app/routes/api/curated_inferences/count.route.ts精选推理计数/api/inferences/countui/app/routes/api/inferences/count.route.ts推理计数/api/datasets/countsui/app/routes/api/datasets/counts.route.ts数据集统计/api/workflow_evaluations/search_runsui/app/routes/api/workflow_evaluations/search_runs/route.ts搜索工作流评估运行/api/evaluations/search_runsui/app/routes/api/evaluations/search_runs/route.ts搜索评估运行/api/evaluations/cancelui/app/routes/api/evaluations/cancel.route.ts取消评估运行/api/function/:function_name/feedback_countsui/app/routes/api/function/$function_name/feedback_counts.route.ts函数反馈计数/api/tensorzero/*ui/app/routes/api/tensorzero/与 Gateway 直连的一组接口见下/api/inference/:inference_idui/app/routes/api/inference/$inference_id/route.ts单条推理详情/api/datasets/datapoints/from-inferenceui/app/routes/api/datasets/datapoints/from-inference/route.ts从推理创建数据点/api/feedbackui/app/routes/api/feedback/route.ts提交反馈/api/autopilot/sessions/:session_id/*ui/app/routes/api/autopilot/sessions/$session_id/Autopilot 会话事件流、授权、提问、消息、中断、配置应用等/api/tensorzero前缀下集中了 UI 对 Gateway 能力的最直接暴露包括inference发起推理、status网关状态、resolve_uuid/:uuidUUID 解析、inference_preview/:inference_id、episode_preview/:episode_id推理/Episode 预览数据完整实现见 ui/app/routes/api/tensorzero/。第三层TensorZero Gateway API 路由Rust/Axum下划线Gateway 是最终的数据源由 Rust 编写、基于 Axum 构建路由定义在 crates/gateway/src/routes/ 下并划分为三类对外路由OTel 追踪定义于 crates/gateway/src/routes/external.rs 的build_otel_enabled_routes()包括POST /inference、POST /batch_inference、POST /feedback以及 OpenAI 兼容路由这类路由会创建名为METHOD ROUTE如POST /batch_inference/{batch_id}的顶层 OpenTelemetry HTTP span对外路由无 OTel同一文件中的build_non_otel_enabled_routes()如/v1/inferences/list_inferences、/v1/datasets/{dataset_name}/datapoints、/v1/optimization/gepa、/workflow_evaluation_run、/status、/health、/metrics内部路由定义于 crates/gateway/src/routes/internal.rs 的build_internal_non_otel_enabled_routes()全部以/internal前缀、下划线分段例如/internal/workflow_evaluations/runs/search、/internal/evaluations/runs、/internal/feedback/{target_id}、/internal/autopilot/v1/sessions、/internal/resolve_uuid/{id}。源码注释明确警示了内部路由的使用边界crates/gateway/src/routes/internal.rs内部路由不稳定、可能随时变更而不另行通知并且不导出任何 OpenTelemetry spans。因此 UI 不应直接依赖内部路由的稳定性而是通过 RR7 资源路由这一层间接层进行隔离。两类路由最终在 crates/gateway/src/routes/mod.rs 的build_api_routes()中合并为同一个 Router并在 crates/gateway/src/router.rs 的build_axum_router()中套上认证、版本头、请求解压等中间件。认证方面只有/status、/health、/internal/autopilot/status三个路由免鉴权见 crates/gateway/src/router.rs。为什么后端统一用下划线从源码看命名一致性的根因后端下划线约定不是 UI 团队的孤立决策而是贯穿 Gateway 全链路的既有事实Rust 生态含 TensorZero 的 axum 路由、tensorzero-core 端点处理函数、数据库列名天然采用 snake_case如variant_sampling_probabilities、inference_counts、get_variant_usage_handler。让 UI 的 RR7 资源路由与 Gateway 内部路由共享workflow_evaluations、search_runs、curated_inferences这些下划线路径段可以降低心智负担前端调用后端时无需做大小写/分隔符转换URL 段直接透传便于检索与审计在仓库中 grepsearch_runs能同时命中 UI 资源路由文件、Gateway 内部路由定义与 handler 三层实现与 Web 标准解耦用户不直接感知后端路径因此后端可以坚持技术风格而前端 URL 则完全从用户体验出发使用连字符。动态段与文件命名约定$前缀、?可选、.route.ts后缀在 ui/app/routes.ts 的配置里可以归纳出 TensorZero 路由的文件命名约定动态路径段统一使用$前缀文件URL 中的:dataset_name、:function_name、:inference_id、:session_id、:run_id等动态段对应实现文件一律命名为$dataset_name、$function_name、$inference_id、$session_id、$run_id目录或文件名这是 React Router v7 的标准文件命名API 资源路由显式加.route.ts后缀与页面路由的route.tsx或组件拆分目录区分例如count.route.ts、search_runs/route.ts、events/stream.route.ts一眼即可识别哪些是纯数据接口可选动态段用?表示/optimization/supervised-fine-tuning/:job_id?是唯一带可选段的页面路由嵌套 layout 成对出现/datasets、/evaluations、/workflow-evaluations、/autopilot、/observability/*均有layout.tsx提供共享布局。实战跟踪一条 URL 的完整调用链下面以两个真实案例展示浏览器 URL → RR7 资源路由 → Gateway 内部路由的完整链路这是 ui/app/routes/README.md 命名规范的落地场景。案例一搜索工作流评估运行用户在/workflow-evaluations页面输入关键词后前端发起请求GET /api/workflow_evaluations/search_runs?project_namexxxqyyyui/app/routes/api/workflow_evaluations/search_runs/route.ts 的loader解析查询参数并通过getTensorZeroClient()调用searchWorkflowEvaluationRuns(100, 0, projectName, query)100是单页条数、0是偏移量UI 侧客户端ui/app/utils/get-tensorzero-client.server.ts根据TENSORZERO_GATEWAY_URL与TENSORZERO_API_KEY或 cookie 中的有效密钥构造请求命中 Gateway 内部路由GET /internal/workflow_evaluations/runs/search定义于 crates/gateway/src/routes/internal.rs结果以 JSON 返回该资源路由还实现了clientLoader防抖逻辑当查询带debounce参数时通过abortableTimeout(request, 500)延迟 500ms 再委托给serverLoader减轻网关压力。案例二获取 Gateway 状态页面挂载时调用useTensorZeroStatusFetcher()内部通过useFetcher().load(/api/tensorzero/status)加载资源路由见 ui/app/routes/api/tensorzero/status.tsloader调用getTensorZeroClient().status()最终命中 Gateway 的GET /status免鉴权路由见 crates/gateway/src/routes/external.rs并把StatusResponse交给页面展示。这两条链路都印证了命名规范的实际作用浏览器里用户看到的是连字符 URL/workflow-evaluationsUI 内部资源路由与 Gateway 走的是下划线路径workflow_evaluations/search_runs两者各司其职、互不混淆。新增路由的实践清单如果你要在 TensorZero UI 中新增一个功能页面或数据接口参照 ui/app/routes.ts 的既有模式按以下步骤操作确定 URL 归属用户可见页面用连字符如/new-feature纯数据接口放入api前缀并用下划线如api/new_feature/stats创建实现文件页面用route.tsx可配layout.tsx嵌套资源接口用route.ts并导出loader/action/clientLoader动态段目录使用$前缀命名在routes.ts注册单条用route(...)批量同前缀用prefix(...)包裹需要共享布局时用嵌套数组结构若需要新后端能力优先复用 Gateway 已存在的内部路由crates/gateway/src/routes/internal.rs并在资源路由的loader中通过getTensorZeroClient()代理如需在 Gateway 新增端点注意内部路由不稳定、不导出 OTel span 的约束并在 crates/gateway/src/routes/external.rs 与 crates/gateway/src/routes/internal.rs 中按注释规范登记。小结TensorZero UI 的路由体系用一个 ui/app/routes.ts 实现了URL → 实现文件的完全可索引映射并用前端连字符、后端下划线的双轨规范同时照顾了用户体验与后端一致性/api-keys、/workflow-evaluations、/supervised-fine-tuning这类连字符 URL 面向浏览器而/api/workflow_evaluations/search_runs、/internal/workflow_evaluations这类下划线路径在 RR7 资源路由与 GatewayAxum内部路由之间无缝对接。理解这套规范与三层路由结构你就能在大型 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），仅供参考