Helicone 开源 LLM 可观测性与 AI 网关平台：从一行代码接入到自托管全栈部署

Helicone 开源 LLM 可观测性与 AI 网关平台：从一行代码接入到自托管全栈部署

【免费下载链接】helicone🧊 Open source LLM observability platform. One line of code to monitor, evaluate, and experiment. YC W23 🍓项目地址: https://gitcode.com/GitHub_Trending/he/helicone

Helicone 是一个开源（Apache 2.0）的 LLM 可观测性平台，同时内置 AI Gateway 能力：开发者只需修改一行baseURL，即可用统一的 OpenAI 兼容 API 访问 100+ 模型，并自动获得请求日志、链路追踪、成本与延迟分析、提示词版本管理与实验评估能力。本文将基于该仓库的 README 与源码实现，讲解平台核心能力、两分钟接入流程、AI Gateway 的智能路由与自动回退原理、完整集成生态，以及基于 Docker Compose 的自托管部署与六大服务架构，帮助读者快速上手并理解其底层实现。

一、Helicone 是什么：AI Gateway 与 LLM 可观测性平台

Helicone 的定位是面向 AI 工程师的 AI Gateway 与 LLM 可观测性平台，其 README 明确列出了一组核心能力：

• AI Gateway：通过 OpenAI API 的 1 个 API Key 访问 100+ AI 模型，并具备智能路由（intelligent routing）与自动回退（automatic fallbacks）能力，README 中宣称 2 分钟即可上手；
• 快速集成：一行代码即可记录来自 OpenAI、Anthropic、LangChain、Gemini、Vercel AI SDK 等框架与提供商的全部请求；
• 观测（Observe）：对 Agent、聊天机器人、文档处理流水线等场景的 traces 与 sessions 进行检视与调试；
• 分析（Analyze）：跟踪 cost、延迟、质量等指标，并可通过一行配置导出到 PostHog 构建自定义仪表盘；
• Playground：在 UI 中快速测试和迭代提示词、会话与 traces；
• Prompt Management：基于生产数据对提示词进行版本管理，通过 AI Gateway 无代码变更地部署提示词；
• Fine-tune：与 OpenPipe、Autonomi 等微调合作伙伴对接；
• 企业级就绪：SOC 2 与 GDPR 合规。

此外，官方提供慷慨的每月免费额度（10k 请求/月），无需绑定信用卡即可开始使用。从仓库结构看，这些能力并非空谈：worker/src/lib/ai-gateway/目录实现了完整的网关路由逻辑，packages/cost/内置了包含 300+ 模型与多家提供商的开源定价数据库，docs/下沉淀了覆盖网关、集成、自托管、REST API 的完整文档。

二、两分钟快速接入：只改 baseURL 的一行代码

README 给出的 Quick Start 非常简单，总共三步：

第 1 步：在官网注册获取 API Key 并充值额度；

第 2 步：修改代码中的baseURL并填入 Helicone API Key。以 OpenAI TypeScript SDK 为例：

import OpenAI from "openai"; const client = new OpenAI({ baseURL: "https://ai-gateway.helicone.ai", apiKey: process.env.HELICONE_API_KEY, }); const response = await client.chat.completions.create({ model: "gpt-4o-mini", // claude-sonnet-4, gemini-2.0-flash 或 https://www.helicone.ai/models 上的任意模型 messages: [{ role: "user", content: "Hello!" }] });

第 3 步：在 Helicone 控制台查看日志，并通过同一个 API Key 访问 100+ 模型。

这段代码的核心价值在于：请求目标（baseURL）从各提供商原生地址切换为 Helicone 网关，而应用代码几乎零改动。仓库的 examples/ai_gateway/index.ts 提供了更完整的端到端示例；sdk/python 与 sdk/typescript 目录则提供了异步日志等 SDK 实现，供多语言场景参考。

值得说明的是，示例中的model字段可以填写任意受支持的模型标识（如claude-sonnet-4、gemini-2.0-flash），这正是 AI Gateway 的核心能力——模型字符串与具体提供商解耦，路由与回退由网关层完成，详见下一节。

三、AI Gateway 深度解析：基于 Attempt 的路由与自动回退

README 将 AI Gateway 描述为"通过 1 个 API Key 访问 100+ 模型 + 智能路由 + 自动回退"。仓库中的 worker/src/lib/ai-gateway/ARCHITECTURE.md 给出了这套机制的权威源码级说明，核心模式是Attempt-based Routing with Fallback（基于尝试的路由与回退）。

3.1 关键类型：Attempt 与 Endpoint

网关的编排围绕Attempt类型展开，它将"端点"与"认证信息"绑定在一起：

interface Attempt { endpoint: Endpoint; // 从注册表编译出的端点 providerKey: ProviderKey; // 实际使用的 API Key authType: "byok" | "ptb"; // BYOK = 用户自带 Key，PTB = 使用 Helicone 的 Key（Pass-Through Billing） priority: number; // 排序权重（1=BYOK，2=PTB） needsEscrow: boolean; // PTB 需要预先预留（escrow）费用额度 source: string; // 调试用，例如 "gpt-4/openai/byok" } interface Endpoint { baseUrl: string; // 请求发送地址 provider: ModelProviderName; // 提供商（openai、anthropic 等） providerModelId: string; // 提供商侧的模型标识 pricing: ModelPricing[]; // 成本计算 contextLength: number; // 最大输入 token 数 maxCompletionTokens: number;// 最大输出 token 数 ptbEnabled: boolean; // 该端点是否支持 PTB supportedParameters: StandardParameter[]; // 端点支持的参数集合 }

从这段类型定义可以提炼出网关的关键设计：BYOK（Bring Your Own Key，用户自带 Key）优先，PTB（Helicone 代付）兜底，两种认证方式统一抽象为authType，并据此决定是否需要对 PTB 尝试做 escrow（费用预留）。

3.2 请求处理流程：SimpleAIGateway 的线性编排

整个请求生命周期由SimpleAIGateway.handle()负责（实现于 worker/src/lib/ai-gateway/SimpleAIGateway.ts），是典型的自顶向下线性流程：

SimpleAIGateway.handle(): ├─ 1. Authenticate（校验 API Key → 获取 orgId） ├─ 2. Parse Request（提取 model 字符串，支持逗号分隔多模型） ├─ 3. Expand Prompts（仅在存在 prompt_id 时触发，合并模板） ├─ 4. Build Attempts（AttemptBuilder 构建排序后的 attempts[]） │ ├─ 解析 model/provider/uid 规格 │ ├─ 检查 BYOK Key 是否可用 │ └─ 从注册表获取 PTB 端点 ├─ 5. Get Disallow List（从 wallet durable object 拉取禁用模型列表） └─ 6. Execute Attempts（按序执行，失败自动回退下一个） ├─ 检查 disallow list ├─ AttemptExecutor.execute()：预留 escrow → 构建请求体 → 注入认证头 → 转发 ├─ 成功 → 返回响应 └─ 失败 → 取消 escrow，尝试下一个

各组件职责如下：

• AttemptBuilder（AttemptBuilder.ts）：解析模型规格，检查 BYOK Key，从注册表获取 PTB 端点，合并用户配置，最终返回按优先级排序的尝试列表；
• AttemptExecutor（AttemptExecutor.ts）：执行单个尝试——为 PTB 预留 escrow、用提供商 helper 构建请求体、注入 Bearer 或x-api-key等认证头、通过网关 forwarder 转发；失败时通过ctx.waitUntil异步取消 escrow，再抛出错误触发重试；
• 错误处理：所有异步操作统一采用Result<T, K>模式（定义于 worker/src/lib/util/results.ts），ok()/err()/isErr()辅助函数让"成功/失败"成为类型系统的一部分，避免异常流的隐式传播。

3.3 端点注册表：成本排序与动态端点

AttemptBuilder所依赖的端点数据来自成本注册表 packages/cost/models/registry.ts。该文件导出的一组方法支撑了整个路由决策：

• getEndpointsByModel(model)：返回按成本排序的全部端点；
• getPtbEndpoints(model)：返回支持 PTB 的端点（同样按成本排序）；
• getModelProviders(model)：返回可用于自动探测提供商的模型集合；
• createPassthroughEndpoint(...)：为未知模型动态创建透传端点；
• buildEndpoint(config, userConfig)：结合用户配置构建端点。

"按成本排序"意味着网关在默认情况下会优先选择更经济的端点，而createPassthroughEndpoint保证了新模型无需手工录入即可被代理，这正是"100+ 模型开箱即用"在实现层面的体现。

四、观测与分析：Trace、Session、成本与指标

接入网关之后，所有请求会被自动记录，形成可观测数据：

• Traces 与 Sessions：README 强调可对 Agent、聊天机器人、文档处理流水线等场景检视和调试 traces 与 sessions。仓库中 docs/features/sessions.mdx 与 docs/features/advanced-usage 等文档进一步说明了会话级别的数据组织方式；
• 成本与延迟分析：README 引导读者查阅 how-we-calculate-cost 了解成本口径。成本计算的底层支撑是 packages/cost 包，其models/目录下存放了 159 个模型定义文件，providers/下则是各提供商的映射与定价逻辑，pricing/提供分层定价（tiers）计算；
• 自定义指标导出：一行配置即可将数据导出到 PostHog 构建自定义仪表盘，相关集成方法见 docs/getting-started/integration-method；
• Playground 与 Prompt Management：在 UI 中快速迭代提示词，并基于生产数据对提示词做版本管理，通过 AI Gateway 无代码变更地部署（历史文档可参考 docs/features/prompts-legacy）；
• 微调（Fine-tune）：通过 OpenPipe 或 Autonomi 等合作伙伴进行模型微调。

五、集成生态：推理提供商与框架一览

README 用两张表格系统梳理了官方支持的集成，以下完整列出。

5.1 推理提供商（Inference Providers）

5.2 框架（Frameworks）

README 同时提醒：该列表可能滞后，最新集成请以 docs/gateway 与 docs/integrations 目录下的文档为准。

六、自托管部署：从 Docker 到生产环境

Helicone 完全开源，支持自托管。README 推荐的路径是 Docker，其次是面向企业工作负载的 Helm，并明确表示不推荐手工部署。

6.1 Docker 快速开始

# 克隆仓库 git clone https://gitcode.com/GitHub_Trending/he/helicone.git cd docker cp .env.example .env # 启动服务 ./helicone-compose.sh helicone up

注意：Docker 编排使用 docker/docker-compose.yml 配合 helper 脚本 docker/helicone-compose.sh 工作。helper 脚本封装了多个 profile，各 profile 对应不同的启动组合：

• infra：仅基础设施（PostgreSQL、ClickHouse、MinIO、MailHog）；
• helicone：完整 Helicone 栈（基础设施 + Jawn + Web）；
• dev：开发模式（基础设施 + Jawn-dev + Web-dev，支持热重载）；
• workers：基础设施 + Worker 服务；
• kafka：基础设施 + Kafka + Zookeeper；
• all：全部（Helicone + Workers + Kafka）。

常用命令示例：./helicone-compose.sh infra up只启动基础设施；./helicone-compose.sh helicone logs jawn查看 Jawn 日志；./helicone-compose.sh helicone down停止栈。up命令默认以-d分离模式运行。

6.2 单容器 All-in-One 镜像

如果需要更简单的部署方式，仓库文档 docs/getting-started/self-host/docker.mdx 提供了helicone/helicone-all-in-one镜像方案：

docker run -d \ --name helicone \ -p 3000:3000 \ -p 8585:8585 \ -p 9080:9080 \ helicone/helicone-all-in-one:latest

本地访问控制台http://localhost:3000，可用curl http://localhost:8585/healthcheck验证 Jawn 服务。该文档还给出了生产服务器部署的关键环境变量：

端口要求：3000（Web 控制台）、8585（Jawn API）、9080（MinIO S3）必须对浏览器可达；5432（PostgreSQL）与 8123（ClickHouse）为内部端口可限制访问。生产部署务必挂载数据卷（PostgreSQL、ClickHouse、MinIO 各一个），否则容器重启会清空全部数据。

6.3 用户与组织初始化

单容器镜像不内置邮件服务，需要手动验证邮箱并创建组织。文档 docs/getting-started/self-host/docker.mdx 给出了完整的 SQL 操作：先用UPDATE "user" SET "emailVerified" = true ...验证邮箱，再通过SELECT查询用户 ID、INSERT INTO organization创建组织、INSERT INTO organization_member将用户加入组织（角色为admin）。若忽略这一步，登录后会出现 "No organization ID found" 错误。

6.4 Helm 与手工部署

对于企业级工作负载，官方提供生产就绪的 Helm Chart，可通过企业邮箱联系获取；README 明确建议优先使用 Docker 或 Helm，手工部署（Manual）"不推荐"，仅在万不得已时参考自托管文档进行。相关排错要点（如NEXT_PUBLIC_IS_ON_PREM=true缺失导致重定向死循环、URL 混用 localhost 与公网 IP 导致登录报 "Invalid origin" 等）也沉淀在 docs/getting-started/self-host/docker.mdx 中。

七、系统架构：六大服务如何协作

README 的 Architecture 一节将 Helicone 拆分为六个组成部分：

• Web：前端平台（Next.js）；
• Worker：代理日志（Cloudflare Workers）；
• Jawn：承载日志收集与业务逻辑的专用服务器（Express + Tsoa）；
• Supabase：应用数据库与认证；
• ClickHouse：分析型数据库；
• Minio：日志对象存储。

这与仓库目录一一对应：web/是 Next.js 前端（599 个组件文件）；worker/是基于 Cloudflare Workers 的代理层，入口在 worker/src/index.ts，通过routerFactory分发到 openai/anthropic/gateway 等各代理路由（worker/src/routers/），日志写入依赖ClickhouseStore、RequestResponseStore、S3Client等实现（worker/src/lib/db/）；valhalla/jawn是 Express + Tsoa 后端，包含面向公开/私有路由的两组控制器与RequestResponseBodyStore、HqlStore、RateLimitStore等存储层；supabase/migrations/与clickhouse/migrations/分别管理两套数据库的数百个增量迁移脚本。

Docker Compose 是理解服务间依赖关系的直观入口：基础设施层包含 PostgreSQL 17.4、ClickHouse 24.3、MinIO（并自动创建request-response-storage、prompt-body-storage、hql-store三个桶）、MailHog（SMTP 测试）、Redis；migrations服务通过 Flyway 与 ClickHouse 迁移脚本初始化 schema，成功后jawn和web才启动。workersprofile 下分别运行OPENAI_PROXY、HELICONE_API、GATEWAY_API、ANTHROPIC_PROXY、GENERATE_API五种 Worker 类型，其中GATEWAY_API的GATEWAY_TARGET默认指向https://openrouter.ai，即网关将流量转发至第三方聚合端点。文档 docs/references/open-source.mdx 对开源架构与数据自主性有进一步说明。

八、数据能力扩展：LLM Cost API、数据导出与 MCP

在核心可观测性之外，README 还介绍了三块数据能力：

• LLM Cost API：Helicone 维护着"最大的开源 API 定价数据库之一"，覆盖 300+ 模型与 OpenAI、Anthropic 等多家提供商，可直接查询。其实现即 packages/cost 包：models/存放各模型定义，providers/存放提供商映射，pricing/提供分层价格计算，并有 packages/tests/cost 下的快照测试保障定价准确性；
• 数据管理与导出：可通过 REST API 查询与导出数据，REST 接口文档位于 docs/rest（覆盖 user、request、session、prompt、organization 等资源）；官方还提供 ETL、请求导出等使用指南；
• MCP 服务器：可通过 MCP 服务器直接访问数据，相关集成见 docs/integrations/tools，仓库 helicone-mcp 目录即其实现源码。

此外，README 强调数据所有权与自主性（Data Ownership and Autonomy），自托管方案从设计上保证数据始终留在用户自己的基础设施内。

九、开源协议与贡献指南

Helicone 采用 Apache v2.0 License 开源。README 欢迎社区贡献文档、集成、成本数据与功能需求，也欢迎通过提交 issue 提出改进想法。仓库根目录还提供了 CONTRIBUTING_GUIDELINES.md 等贡献规范供新贡献者参考。

总结

从 README 与仓库源码的对照来看，Helicone 的价值在于把"多提供商接入、智能路由、自动回退"与"请求级可观测性"合并为一个 OpenAI 兼容的网关层：对外是"改一行 baseURL 即可接入"的极简体验，对内则是SimpleAIGateway+AttemptBuilder/AttemptExecutor+ 成本注册表的清晰架构；配合开源定价数据库、ClickHouse 分析存储与 Docker 一键自托管，它既能作为云上托管服务开箱即用，也能作为完全自主可控的私有化可观测平台部署。对于正在构建 LLM 应用并希望统一管理成本、延迟与质量的团队，Helicone 提供了一个值得实测的落地方案。

【免费下载链接】helicone🧊 Open source LLM observability platform. One line of code to monitor, evaluate, and experiment. YC W23 🍓项目地址: https://gitcode.com/GitHub_Trending/he/helicone