Helicone helicone/async SDK 实战绕过代理直连的 LLM 可观测性与 OpenLLMetry 集成【免费下载链接】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 开源项目中的 sdk/typescript/async/README.md 展开讲解 Node.js 侧绕过 Helicone Proxy、直接上报 LLM 调用追踪的helicone/async包从安装、环境变量配置、HeliconeAsyncOpenAI一行替换接入 OpenAI到heliconeMeta元信息、自定义属性、错误处理与底层 OpenLLMetry/OpenTelemetry 实现。读完本文你将掌握在不引入代理网关的前提下把 OpenAI、Anthropic、Cohere、Bedrock、Google AI Platform、Together 以及 LangChain 的调用统一纳入 Helicone 观测平台的具体方案并理解其与代理模式的能力边界。一、什么是 helicone/async绕过代理的直连日志方案Helicone 提供了两种主流接入方式代理Proxy模式与异步直连Async Logging模式。helicone/async属于后者——它不是一个拦截流量的网关而是一个包装器在应用进程内捕获 LLM 请求与响应直接通过 HTTP 上报给 Helicone 服务端全程不需要部署或指向代理服务器。README 对其定位的描述是A Node.js wrapper for logging LLM traces directly to Helicone, bypassing the proxy, with OpenLLMetry.即借助 OpenLLMetry 实现标准化的 LLM 遥测telemetry将追踪数据直接写入 Helicone。官方文档在 proxy-vs-async 对比页 中对两种模式有完整说明简单来说代理模式适合希望获得缓存、限流、重试等网关能力的场景异步模式则更轻量适用于无法或不希望走代理的生产架构。README 列出的核心特性包括无需代理服务器直接向 Helicone 上报日志基于 OpenLLMetry 的标准 LLM 遥测格式支持自定义属性custom properties追踪支持环境变量配置完整 TypeScript 类型支持。在仓库中该包对应目录为 sdk/typescript/asyncpackage.json声明包名为helicone/async当前版本 2.0.2主入口为 dist/index.js源码入口 index.ts 只做了一件事——重新导出HeliconeAsyncLoggerexport * from ./async_logger/HeliconeAsyncLogger;这一行导出的背后是整个异步日志能力的实现核心 HeliconeAsyncLogger.ts后文会深入拆解。二、安装与环境准备2.1 安装稳定版README 给出的安装命令十分简洁npm install helicone/async需要注意的是README 中的示例代码以require(helicone)方式引入HeliconeAsyncOpenAI。根据官方集成文档 docs/getting-started/integration-method/openai.mdx 的记载OpenAI 异步包装器的完整安装方式为npm install helicone/helicone2.1.19随后以require(helicone)引入即可。也就是说helicone包负责提供面向 OpenAI 的HeliconeAsyncOpenAI高层封装而本仓库中的helicone/async提供底层HeliconeAsyncLogger。两者配合使用即可覆盖从高层 API 到底层遥测的全部需求。2.2 获取 API Key 并配置环境变量先注册 Helicone 账号并在开发者控制台获取 API Key然后设置两个环境变量export HELICONE_API_KEYyour Helicone API key export OPENAI_API_KEYyour OpenAI API key其中HELICONE_API_KEY用于向 Helicone 上报日志Bearer认证OPENAI_API_KEY是你实际调用大模型的凭证。从 HeliconeAsyncLogger.ts 的构造函数可以看到日志上报地址会根据 API Key 的前缀自动切换区域this.baseUrl opts.baseUrl ?? (opts.apiKey.startsWith(sk-helicone-eu-) ? https://eu.api.helicone.ai/v1/trace/log : https://api.helicone.ai/v1/trace/log);即EU 区域的 Keysk-helicone-eu-前缀上报到eu.api.helicone.ai其余 Key 上报到api.helicone.ai你也可以通过baseUrl参数显式覆盖默认地址。三、快速上手把 OpenAI 客户端替换为 HeliconeAsyncOpenAIREADME 给出了最基础的用法实例化HeliconeAsyncOpenAI并在heliconeMeta中传入 Helicone API Key之后所有调用行为与原生 OpenAI 客户端一致const { HeliconeAsyncOpenAI } require(helicone); const openai new HeliconeAsyncOpenAI({ apiKey: process.env.OPENAI_API_KEY, heliconeMeta: { apiKey: process.env.HELICONE_API_KEY, }, }); const chatCompletion await openai.chat.completion.create({ model: gpt-3.5-turbo, messages: [{ role: user, content: Hello world }], }); console.log(chatCompletion.data.choices[0].message);对照官方集成文档 openai.mdx 中 Node.js 标签页的接入步骤核心思想是用 Helicone 的包装类替换原生类// 原写法 const { ClientOptions, OpenAI } require(openai); // 替换为 const { HeliconeAsyncOpenAI as OpenAI, IHeliconeAsyncClientOptions as ClientOptions, } require(helicone);替换完成后Chat、Completion、Embedding 等调用方式与 OpenAI 官方包完全等价业务代码几乎零改动即可获得可观测性。这种一行替换的接入体验与官网欢迎页代码片段 openai-async.tsx 中展示的三步流程安装包 → 设置HELICONE_API_KEY→ 替换 import一致。四、HeliconeMeta 配置项详解heliconeMeta是异步日志的元信息入口README 给出了它的完整接口interface HeliconeMeta { apiKey?: string; // Your Helicone API key custom_properties?: Recordstring, any; // Custom properties to track cache?: boolean; // Enable/disable caching retry?: boolean; // Enable/disable retries user_id?: string; // Track requests by user }各字段含义如下字段类型说明apiKeystringHelicone API Key也可通过HELICONE_API_KEY环境变量提供custom_propertiesRecordstring, any随日志上报的自定义属性用于在控制台按维度筛选与聚合cacheboolean是否启用/禁用缓存见下方边界说明retryboolean是否启用/禁用重试见下方边界说明user_idstring为请求绑定用户标识便于按用户维度分析4.1 与代理模式的能力边界值得特别说明的是官方文档 openai.mdx 在 Node.js 标签页明确提示——异步直连模式会失去代理模式提供的一些附加能力Async logging loses some additional features such as cache, rate limits, and retries也就是说cache、retry这类字段在异步模式下主要用于配置层面的兼容与预留README 将其列入接口而真正的缓存命中、限流、重试等网关级能力是由 Helicone Proxy 在流量路径上实现的如果这些能力是你的硬性需求应优先评估代理模式。从源码结构看HeliconeAsyncLogger.ts 的构造与上报逻辑中也并未实现缓存/限流逻辑与文档描述互相印证。4.2 官方文档中的 IHeliconeMeta 扩展此外openai.mdx 还记录了异步模式下一组更完整的元信息字段interface IHeliconeMeta { apiKey?: string; properties?: { [key: string]: any }; user?: string; baseUrl?: string; onLog?: OnHeliconeLog; onFeedback?: OnHeliconeFeedback; } type OnHeliconeLog (response: Response) Promisevoid; type OnHeliconeFeedback (result: Response) Promisevoid;properties/user分别对应自定义属性与用户标识与 README 的custom_properties、user_id语义一致baseUrl自定义日志上报地址onLog每次日志上报成功后的回调可拿到上报响应的Response对象常用于提取helicone-idonFeedback反馈操作完成后的回调。五、自定义属性与用户追踪自定义属性是异步日志最实用的能力之一。README 给出的示例为每个请求附加project与environment两个业务维度并绑定用户 IDconst openai new HeliconeAsyncOpenAI({ apiKey: process.env.OPENAI_API_KEY, heliconeMeta: { apiKey: process.env.HELICONE_API_KEY, custom_properties: { project: my-project, environment: production, }, user_id: user-123, }, });上报后在 Helicone 控制台即可按project、environment、user_id等维度过滤请求、统计成本与延迟。这非常适合在 A/B 实验、多租户或灰度发布场景下做精细化观测——无需修改业务代码只需在实例化时声明属性即可。5.1 底层withProperties 关联属性对于非 OpenAI 客户端的自定义场景底层 HeliconeAsyncLogger 还暴露了withProperties方法通过 OpenLLMetry 的关联属性机制把自定义键值对挂到当前 trace 上withProperties(properties: Recordstring, string, fn: () any) { return traceloop.withAssociationProperties(properties, fn); }用法大致为const logger new HeliconeAsyncLogger({ apiKey: HELICONE_API_KEY, providers: {...} }); logger.init(); const result logger.withProperties({ project: my-project }, async () { // 这里的 LLM 调用会自动关联 projectmy-project return runLlmCall(); });六、异步调用与错误处理6.1 Async/Await 完整示例README 提供了一个完整的异步调用范例包含 system 提示词、参数控制与返回值处理async function generateResponse() { try { const response await openai.chat.completion.create({ model: gpt-4, messages: [ { role: system, content: You are a helpful assistant. }, { role: user, content: What is the capital of France? }, ], max_tokens: 150, }); return response.data.choices[0].message; } catch (error) { console.error(Error:, error); } }注意返回值通过response.data.choices[0].message获取这与原生 OpenAI SDK 的响应结构一致——包装器不会改变大模型的返回契约。6.2 错误处理模式异步模式下的错误处理与常规 HTTP 客户端相同README 给出的模式是区分带响应体的错误与网络/传输层错误try { const completion await openai.chat.completion.create({ model: gpt-3.5-turbo, messages: [{ role: user, content: Hello }], }); } catch (error) { if (error.response) { console.error(error.response.status); console.error(error.response.data); } else { console.error(error.message); } }存在error.response说明服务端返回了非 2xx 状态码可从response.status与response.data获取详情不存在error.response多为网络超时、DNS 解析失败等传输层异常直接输出error.message。七、底层实现HeliconeAsyncLogger 与 OpenLLMetry/OpenTelemetryHeliconeAsyncOpenAI等高层包装器之所以能够工作底层依赖 HeliconeAsyncLogger.ts 中实现的HeliconeAsyncLogger类。它是理解整个异步日志机制的关键。7.1 构造参数 IHeliconeAsyncLoggerOptionstype IHeliconeAsyncLoggerOptions { apiKey: string; baseUrl?: string; providers: { openAI?: typeof OpenAI; anthropic?: typeof anthropic; cohere?: typeof cohere; bedrock?: typeof bedrock; google_aiplatform?: typeof google_aiplatform; together?: typeof Together; langchain?: { chainsModule?: typeof ChainsModule; agentsModule?: typeof AgentsModule; toolsModule?: typeof ToolsModule; }; }; headers?: Recordstring, string; };可以看出该日志器在设计上是多 Provider 框架级的直接支持 OpenAI、Anthropic、Cohere、Bedrock、Google AI Platform、Together 六家大模型供应商对 LangChain 提供chains、agents、tools三个子模块的插桩支持headers可向上报请求附加自定义 HTTP 头。对应地package.json 的peerDependencies声明了这些供应商 SDK 的版本要求openai ^5.12.0、anthropic-ai/sdk ^0.58.0、cohere-ai ^7.18.0、aws-sdk/client-bedrock-runtime ^3.862.0、google-cloud/aiplatform ^5.3.0、together-ai ^0.21.1、langchain ^0.3.30。7.2 init()启动 OpenLLMetry 插桩构造函数只负责保存配置真正启动遥测的是init()方法init() { traceloop.initialize({ apiKey: this.apiKey, baseUrl: this.baseUrl, disableBatch: true, exporter: new OTLPTraceExporter({ url: this.baseUrl, headers: { Authorization: Bearer ${this.apiKey}, ...this.headers, }, }), instrumentModules: { openAI: this.openAI ?? undefined, anthropic: this.anthropic ?? undefined, // ... 其余 provider 模块 langchain: { chainsModule: this.chainsModule ?? undefined, agentsModule: this.agentsModule ?? undefined, toolsModule: this.toolsModule ?? undefined, }, }, }); }关键点OpenLLMetry 初始化traceloop.initialize来自依赖 traceloop/node-server-sdk ^0.14.6它基于 OpenTelemetry 提供面向 LLM 的标准遥测插桩OTLP HTTP 导出使用opentelemetry/exporter-trace-otlp-http的OTLPTraceExporter通过url直连 Helicone 的 trace 上报端点Authorization: Bearer apiKey完成鉴权禁用批处理disableBatch: true意味着每条 trace 即时导出便于实时观测代价是请求量巨大时会产生更多网络请求按需插桩instrumentModules只会对实际传入的 provider 模块进行插桩未被使用的供应商不会带来额外开销。7.3 数据流向小结从源码可以梳理出异步日志的完整数据链路业务代码调用 LLM SDK │ ▼ Helicone 包装客户端如 HeliconeAsyncOpenAI │ 携带 heliconeMeta ▼ OpenLLMetry 插桩traceloop/node-server-sdk │ 生成 OpenTelemetry Trace ▼ OTLPTraceExporter → POST {baseUrl}api.helicone.ai/v1/trace/log │ Authorization: Bearer HELICONE_API_KEY ▼ Helicone 服务端入库 → 控制台可视化7.4 相关helpers 包的手动日志能力如果你需要记录的不是某个供应商 SDK 调用而是自定义事件如工具调用、向量数据库检索、普通数据事件可以关注同仓库的 sdk/typescript/helpers/manual_logger/HeliconeManualLogger.ts。其中HeliconeManualLogger支持logRequest、logStream、logSingleStream、logSingleRequest等方法并通过 types.ts 中的HeliconeEventTool、HeliconeEventVectorDB、HeliconeEventData类型表达自定义事件结构。它与helicone/async是互补关系后者负责自动化插桩前者负责手动精确控制。八、收集用户反馈onLog 回调与 helicone-id异步模式下要关联用户反馈必须从日志上报响应而非 LLM 响应中提取helicone-id。官方文档 openai.mdx 给出的示例const openai new OpenAI({ apiKey: process.env.OPENAI_API_KEY, heliconeMeta: { apiKey: process.env.HELICONE_API_KEY, onLog: async (response: Response) { const heliconeId response.headers.get(helicone-id); await openai.helicone.logFeedback( heliconeId, HeliconeFeedbackRating.Positive ); }, }, });流程拆解每次 LLM 调用结束后onLog回调被触发入参是日志上报请求的Response从响应头helicone-id中取出本次日志的唯一 ID调用openai.helicone.logFeedback(heliconeId, rating)把用户反馈如HeliconeFeedbackRating.Positive与这条 trace 关联起来。这是异步模式做 RLHF 风格数据收集、人工评估与数据集标注的标准路径。九、最佳实践清单综合 README 与源码以下是异步直连模式下值得遵循的实践建议始终把 API Key 放入环境变量HELICONE_API_KEY、OPENAI_API_KEY等敏感凭证不要硬编码进源码或提交进仓库实现完善的错误处理区分error.response服务端拒绝与传输层异常避免日志上报失败导致主流程中断——从 HeliconeAsyncLogger.ts 可以看到上报异常被捕获后仅console.error不会抛出到业务调用方属于日志失败不影响业务的设计善用自定义属性把项目名、环境、版本、实验分组等元数据放入custom_properties让后续分析与检索拥有更多维度为场景设置合理的超时LLM 调用耗时长根据业务容忍度设置超时值生产环境实现重试逻辑网络抖动不可避免重试策略应当考虑指数退避同时注意异步直连模式本身不提供代理级的重试/缓存/限流能力需要时自行实现或切换到代理模式多供应商场景使用 HeliconeAsyncLogger 统一接入利用providers参数一次初始化多个供应商保持遥测口径一致。十、许可证与进一步阅读helicone/async以 Apache-2.0 协议开源见 sdk/typescript/async/package.json你可以自由用于商业项目。若想继续深入建议阅读仓库内以下资料sdk/typescript/async/README.md本文依据的原始文档sdk/typescript/async/async_logger/HeliconeAsyncLogger.ts异步日志底层实现docs/getting-started/integration-method/openai.mdxOpenAI 异步接入的完整官方指南含 Node.js/Python/Raw 三种方式docs/references/proxy-vs-async.mdx代理模式与异步模式的选型对比sdk/typescript/helpers/manual_logger/HeliconeManualLogger.ts手动日志与自定义事件上报web/components/templates/welcome/steps/codeSnippets/openai-async.tsx官网欢迎页展示的三步接入片段。综上helicone/async为不想引入代理的 Node.js 应用提供了一条极低侵入的 LLM 可观测性路径上层用HeliconeAsyncOpenAI一行替换完成 OpenAI 接入底层以 OpenLLMetry OTLP 实现标准化遥测直传 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考