Helicone 模型注册表请求路由全解析BYOK 与 PTB 双阶段优先级系统深度指南【免费下载链接】helicone Open source LLM observability platform. One line of code to monitor, evaluate, and experiment. YC W23 项目地址: https://gitcode.com/GitHub_Trending/he/heliconeHelicone 的模型注册表Model Registry是其成本包packages/cost的核心组件负责在用户请求指定模型后从多个可用提供商Anthropic、AWS Bedrock、Vertex AI 等中选择最合适的端点发起调用。本文以仓库中的 FLOWS.md 为骨架结合 types.ts、registry.ts、build-indexes.ts 等源码系统讲解请求路由的黄金法则、双阶段流程、byok_only开关、成本排序规则、模型字符串格式与底层类型系统帮助你理解并驾驭 Helicone 的多提供商路由与计费逻辑。核心概念四种基础角色在深入路由流程之前先明确模型注册表涉及的四个基础概念PTBPass-Through Billing直通计费由 Helicone 统一管理 API 密钥并向用户收取使用费用户无需自行申请各提供商密钥。BYOKBring Your Own Key自带密钥用户提供自己的 API 密钥由各提供商直接向用户计费Helicone 只负责转发请求。Provider提供商托管模型的服务方例如 Anthropic、AWS Bedrock、Vertex AI、OpenRouter。Endpoint端点模型的一个具体部署实例例如 Bedrock us-east-1 区域部署、Vertex us-central1 区域部署。同一个模型可以对应多个端点。这四个概念是后续所有路由规则的基础一次请求最终都要落到「某个提供商下的某个端点」而 PTB 与 BYOK 则决定了该端点使用的是谁的密钥、走谁的账单。路由优先级黄金法则与双阶段流程黄金法则模型注册表的路由逻辑遵循一条不可动摇的黄金法则先按成本排序尝试所有 BYOK 端点再按成本排序尝试所有 PTB 端点。也就是说只要用户配置了某个提供商的密钥Helicone 就优先使用用户自己的密钥BYOK发起请求只有当所有 BYOK 端点都失败密钥无效、限流、网络错误等时才会降级到 Helicone 托管的密钥PTB继续尝试。完整优先级流程图以用户请求claude-3.5-haiku可用提供商为 Anthropic、Bedrock、Vertex为例完整流程如下User Request: claude-3.5-haiku ↓ 1. Identify Available Providers [Anthropic, Bedrock, Vertex] ↓ 2. Phase 1: Try ALL BYOK endpoints (sorted by cost) - Check which providers user has keys for - Sort BYOK endpoints by cost - Attempt each BYOK endpoint in order: • Success? → Return response ✓ • Failed? → Try next BYOK endpoint - All BYOK exhausted? → Continue to Phase 2 ↓ 3. Phase 2: Try ALL PTB endpoints (sorted by cost) - Get all PTB-enabled endpoints - Filter out providers marked as byok_only - Sort PTB endpoints by cost - Attempt each PTB endpoint in order: • Success? → Return response ✓ • Failed? → Try next PTB endpoint ↓ 4. All endpoints exhausted → Return error从源码看这一「阶段分离」的设计在注册表 API 中体现得非常清晰registry.ts 提供了getPtbEndpoints(model)专门返回某模型的全部 PTB 端点索引而 BYOK 侧则使用getModelProviderConfig/buildEndpoint按用户配置动态构建端点registry.ts二者是两套独立 API天然对应 Phase 1 与 Phase 2。关键行为三大路由规则1. 双阶段Two-Phase策略Phase 1全部 BYOK 端点按成本排序。Phase 2全部 PTB 端点按成本排序。BYOK 端点总是被完全耗尽之后才会尝试任意一个 PTB 端点——不存在「BYOK 失败一个就切 PTB」的混合穿插。这一规则的业务含义是Helicone 尊重用户自带密钥的优先权同时保证在用户密钥不可用时仍能通过 PTB 兜底完成请求兼顾成本偏好与可用性。2. 按提供商粒度的 BYOK-Only 模式byok_only标志的粒度是per-provider按提供商而非 per-model按模型。当用户对某提供商设置byok_only: true时该提供商将从 Phase 2PTB中被剔除——即该提供商只允许走用户自己的密钥。例如用户对 Anthropic 设置byok_only: truePhase 1若用户有 Anthropic 密钥则尝试 Anthropic BYOK 端点Phase 2Anthropic 的 PTB 端点被跳过但 Bedrock / Vertex 的 PTB 端点仍然可用。从类型定义看byok_only存在于用户的密钥配置ProviderKey / UserEndpointConfig 体系中与端点自身的ptbEnabled标志相互配合ptbEnabled决定「该端点是否允许 PTB 计费」byok_only则从用户侧按提供商「封禁 PTB 降级」。types.ts 中UserEndpointConfig包含region、location、projectId、baseUri、deploymentName、resourceName、apiVersion、crossRegion等字段正是用户在请求时携带的提供商相关配置用于从模板合并出具体的 BYOK 端点。3. 阶段内按成本升序排序BYOK 端点按各自关联成本排序PTB 端点按各自定价排序每个阶段内总是先尝试最便宜的端点实现成本优先的路由。这一排序在源码中是显式实现的build-indexes.ts 定义了sortByCost取端点定价数组第一个档位的input output之和作为成本比较依据并依次对modelToEndpoints、modelToPtbEndpoints、endpointConfigIdToPtbEndpoints等全部端点索引做升序排序// packages/cost/models/build-indexes.ts const sortByCost (a: Endpoint, b: Endpoint) { const aCost (a.pricing[0]?.input ?? 0) (a.pricing[0]?.output ?? 0); const bCost (b.pricing[0]?.input ?? 0) (b.pricing[0]?.output ?? 0); return aCost - bCost; }; modelToEndpoints.forEach((endpoints) endpoints.sort(sortByCost)); modelToPtbEndpoints.forEach((endpoints) endpoints.sort(sortByCost));这意味着「最便宜优先」不是运行时的临时比较而是注册表构建阶段就已固化在索引中的有序结果路由时直接顺序遍历即可。示例场景四种典型路由组合以下场景完整复现 FLOWS.md 中的路由推演文中的单价为文档示意数据用于说明排序逻辑真实价格以各模型 endpoints 配置文件为准。场景 1混合 BYOK 与 PTB用户配置了 Anthropic 与 Bedrock 密钥成本关系为anthropic bedrock vertexModel: claude-3.5-haiku User Keys: {anthropic: configured, bedrock: configured} Costs: anthropic bedrock vertex Phase 1 - BYOK (sorted by cost): 1. anthropic (BYOK) - $0.25/1K → Try users Anthropic key 2. bedrock (BYOK) - $0.30/1K → Try users Bedrock key Phase 2 - PTB (sorted by cost): 3. anthropic (PTB) - $0.25/1K → Try Helicones Anthropic key 4. bedrock (PTB) - $0.30/1K → Try Helicones Bedrock key 5. vertex (PTB) - $0.35/1K → Try Helicones Vertex key该场景展示了最典型的路径先耗尽用户的两个密钥全部失败后再依次尝试 Helicone 的三个托管密钥。场景 2某提供商启用 BYOK-only用户对 Anthropic 设置byok_only: true对 Bedrock 不设置Model: claude-3.5-haiku User Keys: { anthropic: {key: sk-ant-..., byok_only: true}, bedrock: {key: AKIA..., byok_only: false} } Phase 1 - BYOK: 1. anthropic (BYOK) → Try users key 2. bedrock (BYOK) → Try users key Phase 2 - PTB: 3. bedrock (PTB) → Try Helicones key 4. vertex (PTB) → Try Helicones key (Anthropic PTB skipped due to byok_onlytrue)注意 Phase 2 中 Anthropic 被跳过但 Bedrock 与 Vertex 的 PTB 兜底不受影响。场景 3未配置任何 BYOK 密钥Model: claude-3.5-haiku User Keys: None configured Phase 1 - BYOK: (Skip - no user keys) Phase 2 - PTB (sorted by cost): 1. anthropic (PTB) - $0.25/1K → Try first (cheapest) 2. bedrock (PTB) - $0.30/1K → Try if anthropic fails 3. vertex (PTB) - $0.35/1K → Try if bedrock fails这是纯 PTB 场景Phase 1 直接跳过Phase 2 按成本从低到高依次兜底。场景 4全部 BYOK 且部分提供商开启 byok_onlyModel: gpt-4 User Keys: { openai: {key: sk-..., byok_only: false}, azure: {key: ..., byok_only: true}, bedrock: {key: ..., byok_only: true} } Phase 1 - BYOK (all attempted): 1. openai (BYOK) → Try users OpenAI key 2. azure (BYOK) → Try users Azure key 3. bedrock (BYOK) → Try users Bedrock key Phase 2 - PTB (filtered): 4. openai (PTB) → Only OpenAI PTB available (Azure and Bedrock PTB skipped due to byok_onlytrue)byok_only只影响 Phase 2 的 PTB 可用性不影响 Phase 1 中用户自己密钥的尝试——所以 Azure、Bedrock 的用户密钥照常被尝试。模型字符串格式如何指定模型、提供商与部署用户请求中的模型字符串支持三种由粗到细的粒度路由逻辑相应收敛格式示例路由行为仅模型名claude-3.5-haiku尝试所有提供商的端点按成本顺序模型/提供商claude-3.5-haiku/bedrock仅尝试 Bedrock 提供商模型/提供商/部署claude-3.5-haiku/bedrock/us-west-2仅尝试 Bedrock us-west-2 部署在源码中字符串解析由 provider-helpers.ts 的parseModelString完成以/切分字符串parts.length 1时校验模型是否在注册表中存在未知模型且未指定提供商时直接报错parts.length 2时校验提供商合法性parts.length 3时第三段作为customUid即部署标识传入。此外它还处理:online后缀与历史模型名映射如claude-3.5-sonnet→claude-3.5-sonnet-v2以保证向后兼容。数据架构与类型系统分层数据组织模型注册表采用层级结构管理模型配置Registry ├── ModelProviderConfig (Base Template) │ ├── Provider (e.g., bedrock) │ ├── Model ID (e.g., anthropic.claude-3-5-haiku) │ ├── Pricing (base costs) │ ├── Context limits │ └── EndpointConfigs (deployment variations) │ ├── us-east-1: { regional overrides } │ └── us-west-2: { regional overrides } │ └── Endpoint (Resolved Instance) ├── Everything from ModelProviderConfig ├── Specific deployment merged ├── baseUrl (fully constructed) └── ptbEnabled flag这一「模板 部署覆盖」的设计在 types.ts 与 build-indexes.ts 的mergeConfigs中落地每个部署配置EndpointConfig在构建索引时与基础模板ModelProviderConfig合并产出最终的 Endpoint 实例其中endpointConfig.providerModelId ?? modelProviderConfig.providerModelId之类的??合并语义保证了部署级字段对模板级字段的按需覆盖。三类关键类型及职责1. ModelProviderConfig模板某个「模型 × 提供商」组合的蓝图包含基础配置与全部可能的部署变体endpointConfigs静态存储在各作者的endpoints.ts文件中目录结构见 packages/cost/models/authors/同时用于生成 BYOK 端点与 PTB 端点。其真实定义types.ts包含providerModelId、provider、author、pricing、contextLength、maxCompletionTokens、ptbEnabled、supportedParameters、endpointConfigs等字段另有priority数字越小优先级越高、requireExplicitRouting、providerModelIdAliases模型 ID 别名用于索引别名查询见 build-indexes.ts等进阶配置。2. Endpoint运行时实例解析完成、可直接使用的配置由ModelProviderConfig与具体部署合并生成包含实际 URL、请求头与定价带ptbEnabled标志决定计费模式。在 registry.ts 的buildEndpoint中可以看到BYOK 端点的构建流程是调用buildModelId根据用户配置如区域、资源名拼装出最终模型 ID然后产出带ptbEnabled: false的运行时端点——BYOK 端点总是关闭 PTB 计费。3. ProviderKey用户配置用户存储的 API 凭证含byok_only标志用于排除 PTB包含提供商特定配置区域、资源名等请求时从数据库检索。类型如何支撑双阶段流程Phase 1 (BYOK): 1. Query DB for ProviderKeys → Get users credentials 2. Use ModelProviderConfig as template 3. Merge with users config → Create BYOK Endpoint 4. Set ptbEnabled false 5. Attempt request with users key Phase 2 (PTB): 1. Get pre-built PTB Endpoints from registry 2. Filter out providers where byok_only true 3. These already have ptbEnabled true 4. Attempt request with Helicones keysPTB 端点是注册表在构建阶段就预先解析并索引好的modelToPtbEndpoints索引见 build-indexes.ts仅当endpoint.ptbEnabled为 true 才进入该索引运行时零成本读取BYOK 端点则需在请求时结合用户密钥与模板现场构建。源码级实例claude-3.5-haiku 的多提供商端点以 FLOWS.md 反复使用的claude-3.5-haiku为例其在 endpoints.ts 中注册了 5 个提供商的端点anthropic原生 API、vertexus-east5区域、bedrockus-east-1区域crossRegion: true、openrouter兜底、helicone。以 Bedrock 端点为例// packages/cost/models/authors/anthropic/claude-3.5-haiku/endpoints.ts claude-3.5-haiku:bedrock: { provider: bedrock, author: anthropic, providerModelId: anthropic.claude-3-5-haiku-20241022-v1:0, version: 20241022, crossRegion: true, pricing: [ { threshold: 0, input: 0.0000008, // $0.80/1M input tokens output: 0.000004, // $4.00/1M output tokens cacheMultipliers: { cachedInput: 0.1, write5m: 1.25 }, }, ], contextLength: 200000, maxCompletionTokens: 8192, ptbEnabled: true, endpointConfigs: { us-east-1: {} }, responseFormat: ANTHROPIC, }这份真实配置同时印证了前文多个机制ptbEnabled: true使该端点进入 PTB 索引endpointConfigs定义部署变体us-east-1pricing数组的第一档threshold: 0正是sortByCost排序时取用的成本依据providerModelId与用户请求字符串中的模型名claude-3.5-haiku是两套命名后者通过parseModelString与注册表索引定位到前者。同名模型在不同提供商下的成本一致这里均为$0.80/1M输入因此排序退化为按配置顺序稳定执行而文档场景中「成本不同」的情况则会触发严格的最便宜优先。补充机制OpenRouter 兜底端点与三级优先级在 BYOK优先级 1与 PTB优先级 2之外模型注册表还引入了 OpenRouter 作为通用兜底提供商。根据 OPENROUTER_ENDPOINT_GUIDE.mdOpenRouter 端点的priority: 3排在 BYOK 与 PTB 之后由于 OpenRouter 会动态路由到不同上游提供商、成本不固定其端点定价采用「最坏情况最贵端点× 1.055OpenRouter 5.5% 手续费」作为托管金escrow占位价实际费用以响应中的usage.cost为准。并且该指南明确要求OpenRouter 兜底端点必须保持ptbEnabled: true端点示例中claude-3.5-haiku:openrouter的input: 0.000000844正是0.80 × 1.055的计算结果从而在 PTB 阶段兜底覆盖更多模型。总结Helicone 模型注册表的路由体系可以浓缩为三个层次阶段优先BYOK 永远先于 PTB 被尝试两者内部各自按成本升序按提供商管控byok_only可对单个提供商禁用 PTB 兜底ptbEnabled决定端点是否参与 PTB 计费模板 部署的合并模型ModelProviderConfig是静态蓝图Endpoint是运行时实例ProviderKey是用户侧配置三者共同支撑起双阶段路由的全部信息需求。理解这套机制可以帮助你在接入 Helicone 网关时精准控制密钥策略与成本优先级想省成本就配置 BYOK 并开启byok_only想保证高可用就保留 PTB 兜底想全站统一账单就只走 PTB。相关实现均可继续深入 packages/cost/models/ 目录下的源码、索引构建与各作者端点配置进行验证。【免费下载链接】helicone Open source LLM observability platform. One line of code to monitor, evaluate, and experiment. YC W23 项目地址: https://gitcode.com/GitHub_Trending/he/helicone创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考