Helicone 网关接入 Google GeminiTypeScript原生 fetch 代理请求实战指南【免费下载链接】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 开源仓库中的 Gemini TypeScript 示例完整讲解如何通过 Helicone AI 网关以原生fetch方式调用 Google Gemini 模型实现不改一行业务逻辑即可获得全链路可观测性的效果。读完本文你将掌握Helicone-Auth、Helicone-Target-Url、Helicone-User-Id、Helicone-Property-*等网关头的配置方法、Gemini REST API 请求体结构以及如何用官方 TypeScript SDK 与 Python Instructor 两种方式接入并能在 Helicone 控制台中按用户、属性、会话维度检索与分析请求。一、示例解决的问题给 Gemini 请求加上观测层示例所在的目录是 examples/gemini-instructor-example/typescript它演示的核心思路是不直接向 Google 的generativelanguage.googleapis.com发请求而是把请求发给 Helicone 网关gateway.helicone.ai由网关代为转发到 Google并在转发前后完成日志记录、成本核算、用户与属性标注等观测工作。这样做的好处是应用代码里无需引入任何 Helicone SDK仅靠 HTTP 头和 URL 改写即可接入网关解析请求头后会把user_id、自定义属性、会话信息等一并写入 Helicone 的数据链路开发者可以继续使用 Gemini 原生的generateContentREST 接口与请求体格式学习成本几乎为零。从网关侧看这些头部正是由网关的请求头解析模块负责读取的。核心实现位于 worker/src/lib/models/HeliconeHeaders.ts其中Helicone-Target-URL头被读取为targetBaseUrlHeliconeHeaders.ts 第 359 行用于确定请求要转发到的真实上游地址Helicone-User-Id头被读取为userId第 387 行用于关联到具体终端用户以Helicone-Property-开头的头会被统一收进heliconeProperties第 473-485 行成为该请求可检索的自定义属性。理解了这个解析链路就能明白示例中每个头字段的用途。二、环境准备与前置条件运行本示例需要以下条件依赖说明Node.js 16运行时示例基于fetch全局 API需 Node 16Helicone API 密钥用于Helicone-Auth头认证网关身份Google Gemini API 密钥以key查询参数形式透传给 Google示例目录下包含的文件如下gemini_example.ts基于原生fetch的完整示例主程序gemini_example_sdk.ts基于 Google 官方google/genaiSDK 的接入示例package.json依赖与脚本定义run.sh一键运行脚本含环境检查tsconfig.jsonTypeScript 编译配置。1. 进入示例目录cd examples/gemini-instructor-example/typescript2. 创建.env文件在示例目录下新建.env写入HELICONE_API_KEYyour_helicone_api_key GEMINI_API_KEYyour_gemini_api_key USER_IDtest_user_123三个变量的作用分别是网关认证、Gemini 模型访问、以及在 Helicone 控制台标识本次请求归属的用户。示例代码在读取时做了容错处理USER_ID未设置时会回退为default_user见 gemini_example.ts 第 10 行。3. 安装依赖npm install依赖清单见 package.json运行时仅需dotenv加载环境变量开发期需要typescript、ts-node、types/node。4. 运行示例npm startnpm start实际执行的是ts-node gemini_example.ts。也可以直接使用仓库提供的脚本 run.sh它会依次检查node、npm、.env是否存在缺失时给出明确提示并在首次运行时自动npm install./run.sh程序会打印如下信息并输出模型返回的文本 Making Gemini API call through Helicone gateway User ID: test_user_123 Prompt: List 3 classic sci-fi movies from the 1980s. Response ...三、核心实现一条被网关接管的 Gemini 请求gemini_example.ts的关键在于构造requestConfig把原本指向 Google 的请求整体搬到 Helicone 网关上。以下代码完整来自示例主程序gemini_example.ts 第 12-61 行async function makeGeminiRequest( prompt: string, analyticsPermission: boolean true ) { const requestConfig { url: ${HELICONE_URL}/v1beta/models/gemini-1.5-flash-latest:generateContent?key${GEMINI_API_KEY}, headers: { Content-Type: application/json, Helicone-Auth: Bearer ${HELICONE_API_KEY}, Helicone-Target-Url: https://generativelanguage.googleapis.com, Helicone-User-Id: USER_ID, } as Recordstring, string, body: { contents: [ { role: user, parts: [{ text: prompt }], }, ], generationConfig: { temperature: 0.7, maxOutputTokens: 8192, }, }, }; const response await fetch(requestConfig.url, { method: POST, headers: requestConfig.headers, body: JSON.stringify(requestConfig.body), }); if (!response.ok) { throw new Error( HTTP error! status: ${response.status}, message: ${await response.text()} ); } const data await response.json(); return data; }这段代码里有四个关键点值得展开3.1 URL 结构网关路径 原路径 key 查询参数请求 URL 为https://gateway.helicone.ai/v1beta/models/gemini-1.5-flash-latest:generateContent?key${GEMINI_API_KEY}主机从generativelanguage.googleapis.com替换为 Helicone 网关gateway.helicone.ai路径/v1beta/models/模型名:generateContent保持 Gemini REST API 的原样gemini-1.5-flash-latest可替换为其他模型如gemini-2.0-flashGemini 的 API 密钥通过key查询参数透传网关不会消费这个密钥它只负责把请求转发给上游。需要说明的是示例主程序中的HELICONE_URL来自process.env.HELICONE_URL第 9 行README 中则直接写为https://gateway.helicone.ai。若你自托管了 Helicone 网关可把该变量指向自己的网关地址。3.2 请求头Helicone 的三个基础头头字段值作用Helicone-AuthBearer ${HELICONE_API_KEY}向网关出示 Helicone API 密钥完成认证。网关侧从helicone-auth读取见 HeliconeHeaders.ts 第 354 行Helicone-Target-Urlhttps://generativelanguage.googleapis.com告诉网关把请求转发到哪个上游地址这是网关路由的关键Helicone-User-Id${USER_ID}为该请求绑定用户标识用于控制台的用户维度分析除了这三个头README 的请求配置中还演示了两个自定义属性头README.md 第 61-64 行Helicone-Property-App: cursor-extension-cursorrules, Helicone-Property-AnalyticsPermission: analyticsPermission ? true : false,Helicone-Property-*是任意自定义属性的统一命名约定网关会把该前缀之后的字符串作为属性名、头值为属性值统一收进请求的可检索属性集合见 HeliconeHeaders.ts 第 473-485 行。这也是 Helicone 支持任意业务维度打标的实现基础。3.3 请求体保持 Gemini 原生generateContent格式示例请求体完全遵循 Gemini REST API 规范{ contents: [ { role: user, parts: [{ text: List 3 classic sci-fi movies from the 1980s. }] } ], generationConfig: { temperature: 0.7, maxOutputTokens: 8192 } }contents对话内容数组role支持user/model多轮对话可追加多个元素parts内容块text即文本输入generationConfig生成参数示例给出temperature: 0.7采样温度与maxOutputTokens: 8192最大输出 token 数可按需增减。由于请求体没有被网关改写你在 Google 侧如何调 Gemini这里就如何写迁移成本几乎为零。3.4 响应解析按 Gemini 返回结构取文本响应 JSON 中生成文本位于candidates[0].content.parts[0].text示例中通过可选链安全取值第 79-80 行const responseText response.candidates?.[0]?.content?.parts?.[0]?.text || No response text;四、进阶方式用 Google 官方 SDK 走 Helicone 网关除了裸fetch仓库还提供了基于 Google 官方google/genaiSDK 的接入示例 gemini_example_sdk.ts。其思路是把网关地址注入 SDK 的httpOptionsimport { GoogleGenAI } from google/genai; const genAI new GoogleGenAI({ apiKey: GOOGLE_API_KEY, vertexai: true, httpOptions: { baseUrl: https://gateway.helicone.ai, headers: { Helicone-Auth: Bearer HELICONE_API_KEY, Helicone-Target-URL: https://generativelanguage.googleapis.com, }, }, }); async function generateContent() { const response await genAI.models.generateContent({ model: gemini-2.0-flash-001, contents: Why is the sky blue?, }); console.log(response.text); } generateContent();要点SDK 的apiKey仍然填 Google 的密钥或按你的鉴权方式配置httpOptions.baseUrl指向网关httpOptions.headers注入 Helicone 认证头与目标地址头注意此处使用了Helicone-Target-URL全大写 URL与 README 中的Helicone-Target-Url写法不同——网关在解析时通过this.headers.get(Helicone-Target-URL)读取第 359 行HTTP 头本身不区分大小写两种写法均被正确识别这种方式适合已经深度使用官方 SDK、希望最小改动的项目。五、多用户场景为什么要在请求里带 User ID仓库同名目录下的 Python 示例 examples/gemini-instructor-example/python 特意演示了带与不带user_id的对比两次请求在功能上完全一致但只有第二次会与用户test_user_123关联从而可以在 Helicone 控制台中按用户检索到它。这里有一个值得注意的客户端差异Google 官方 Python SDK 不支持在单次请求上动态传extra_headers必须把 Helicone 头放进default_metadata随客户端初始化见 python/README.md 的说明。因此多用户场景下要么为每个用户创建独立客户端实例要么在每次请求前重新配置客户端。而 TypeScript 的原生fetch方式没有这个限制——每个请求的头都是独立的天然适合多用户、动态打标的场景。六、在 Helicone 控制台验证请求运行示例后打开 Helicone 控制台检查以下几点请求列表中出现该条 Gemini 调用记录模型、耗时、token 消耗与成本已自动统计请求详情中能查看到user_id为test_user_123或你在.env中设置的值若在头中添加了Helicone-Property-*对应属性会出现在请求的自定义属性中可用于后续筛选与报表分析。七、常见问题排查现象排查方向401/认证失败检查HELICONE_API_KEY是否正确、是否以Bearer前缀发送上游返回 4xx确认GEMINI_API_KEY有效确认请求体符合 GeminigenerateContent规范请求超时或网络错误确认运行环境能访问gateway.helicone.ai若自托管检查HELICONE_URL指向的网关地址控制台查不到请求确认头字段名拼写无误尤其是Helicone-Auth与Helicone-Target-Url此外run.sh中内置了环境自检node/npm缺失或.env不存在时会在运行前给出明确报错可作为快速排错入口。八、总结本示例展示了接入 Helicone 网关最轻量的一条路径不改 Gemini 的请求协议只改 URL 主机与三个网关头即可让 Google Gemini 调用进入 Helicone 的可观测体系。无论你倾向裸fetch的透明可控、官方 SDK 的零成本迁移还是结合 Instructor 的结构化输出参考同目录 Python 示例核心原理一致——网关替你转发、记录、打标而你的业务代码始终保持简洁。更完整的网关能力统一 OpenAI 兼容 API、多 provider 路由、缓存、会话追踪等可继续阅读仓库中的 docs/gateway/overview.mdx 与 docs/gateway/integrations/overview.mdx网关头部的完整解析逻辑可深入 worker/src/lib/models/HeliconeHeaders.ts 查看。【免费下载链接】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），仅供参考 
长河君 · 2026/9/17 13:24:10 · 阅读 1.2k Helicone 网关接入 Google Gemini（TypeScript）：原生 fetch 代理请求实战指南
Helicone 网关接入 Google GeminiTypeScript原生 fetch 代理请求实战指南【免费下载链接】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 开源仓库中的 Gemini TypeScript 示例完整讲解如何通过 Helicone AI 网关以原生fetch方式调用 Google Gemini 模型实现不改一行业务逻辑即可获得全链路可观测性的效果。读完本文你将掌握Helicone-Auth、Helicone-Target-Url、Helicone-User-Id、Helicone-Property-*等网关头的配置方法、Gemini REST API 请求体结构以及如何用官方 TypeScript SDK 与 Python Instructor 两种方式接入并能在 Helicone 控制台中按用户、属性、会话维度检索与分析请求。一、示例解决的问题给 Gemini 请求加上观测层示例所在的目录是 examples/gemini-instructor-example/typescript它演示的核心思路是不直接向 Google 的generativelanguage.googleapis.com发请求而是把请求发给 Helicone 网关gateway.helicone.ai由网关代为转发到 Google并在转发前后完成日志记录、成本核算、用户与属性标注等观测工作。这样做的好处是应用代码里无需引入任何 Helicone SDK仅靠 HTTP 头和 URL 改写即可接入网关解析请求头后会把user_id、自定义属性、会话信息等一并写入 Helicone 的数据链路开发者可以继续使用 Gemini 原生的generateContentREST 接口与请求体格式学习成本几乎为零。从网关侧看这些头部正是由网关的请求头解析模块负责读取的。核心实现位于 worker/src/lib/models/HeliconeHeaders.ts其中Helicone-Target-URL头被读取为targetBaseUrlHeliconeHeaders.ts 第 359 行用于确定请求要转发到的真实上游地址Helicone-User-Id头被读取为userId第 387 行用于关联到具体终端用户以Helicone-Property-开头的头会被统一收进heliconeProperties第 473-485 行成为该请求可检索的自定义属性。理解了这个解析链路就能明白示例中每个头字段的用途。二、环境准备与前置条件运行本示例需要以下条件依赖说明Node.js 16运行时示例基于fetch全局 API需 Node 16Helicone API 密钥用于Helicone-Auth头认证网关身份Google Gemini API 密钥以key查询参数形式透传给 Google示例目录下包含的文件如下gemini_example.ts基于原生fetch的完整示例主程序gemini_example_sdk.ts基于 Google 官方google/genaiSDK 的接入示例package.json依赖与脚本定义run.sh一键运行脚本含环境检查tsconfig.jsonTypeScript 编译配置。1. 进入示例目录cd examples/gemini-instructor-example/typescript2. 创建.env文件在示例目录下新建.env写入HELICONE_API_KEYyour_helicone_api_key GEMINI_API_KEYyour_gemini_api_key USER_IDtest_user_123三个变量的作用分别是网关认证、Gemini 模型访问、以及在 Helicone 控制台标识本次请求归属的用户。示例代码在读取时做了容错处理USER_ID未设置时会回退为default_user见 gemini_example.ts 第 10 行。3. 安装依赖npm install依赖清单见 package.json运行时仅需dotenv加载环境变量开发期需要typescript、ts-node、types/node。4. 运行示例npm startnpm start实际执行的是ts-node gemini_example.ts。也可以直接使用仓库提供的脚本 run.sh它会依次检查node、npm、.env是否存在缺失时给出明确提示并在首次运行时自动npm install./run.sh程序会打印如下信息并输出模型返回的文本 Making Gemini API call through Helicone gateway User ID: test_user_123 Prompt: List 3 classic sci-fi movies from the 1980s. Response ...三、核心实现一条被网关接管的 Gemini 请求gemini_example.ts的关键在于构造requestConfig把原本指向 Google 的请求整体搬到 Helicone 网关上。以下代码完整来自示例主程序gemini_example.ts 第 12-61 行async function makeGeminiRequest( prompt: string, analyticsPermission: boolean true ) { const requestConfig { url: ${HELICONE_URL}/v1beta/models/gemini-1.5-flash-latest:generateContent?key${GEMINI_API_KEY}, headers: { Content-Type: application/json, Helicone-Auth: Bearer ${HELICONE_API_KEY}, Helicone-Target-Url: https://generativelanguage.googleapis.com, Helicone-User-Id: USER_ID, } as Recordstring, string, body: { contents: [ { role: user, parts: [{ text: prompt }], }, ], generationConfig: { temperature: 0.7, maxOutputTokens: 8192, }, }, }; const response await fetch(requestConfig.url, { method: POST, headers: requestConfig.headers, body: JSON.stringify(requestConfig.body), }); if (!response.ok) { throw new Error( HTTP error! status: ${response.status}, message: ${await response.text()} ); } const data await response.json(); return data; }这段代码里有四个关键点值得展开3.1 URL 结构网关路径 原路径 key 查询参数请求 URL 为https://gateway.helicone.ai/v1beta/models/gemini-1.5-flash-latest:generateContent?key${GEMINI_API_KEY}主机从generativelanguage.googleapis.com替换为 Helicone 网关gateway.helicone.ai路径/v1beta/models/模型名:generateContent保持 Gemini REST API 的原样gemini-1.5-flash-latest可替换为其他模型如gemini-2.0-flashGemini 的 API 密钥通过key查询参数透传网关不会消费这个密钥它只负责把请求转发给上游。需要说明的是示例主程序中的HELICONE_URL来自process.env.HELICONE_URL第 9 行README 中则直接写为https://gateway.helicone.ai。若你自托管了 Helicone 网关可把该变量指向自己的网关地址。3.2 请求头Helicone 的三个基础头头字段值作用Helicone-AuthBearer ${HELICONE_API_KEY}向网关出示 Helicone API 密钥完成认证。网关侧从helicone-auth读取见 HeliconeHeaders.ts 第 354 行Helicone-Target-Urlhttps://generativelanguage.googleapis.com告诉网关把请求转发到哪个上游地址这是网关路由的关键Helicone-User-Id${USER_ID}为该请求绑定用户标识用于控制台的用户维度分析除了这三个头README 的请求配置中还演示了两个自定义属性头README.md 第 61-64 行Helicone-Property-App: cursor-extension-cursorrules, Helicone-Property-AnalyticsPermission: analyticsPermission ? true : false,Helicone-Property-*是任意自定义属性的统一命名约定网关会把该前缀之后的字符串作为属性名、头值为属性值统一收进请求的可检索属性集合见 HeliconeHeaders.ts 第 473-485 行。这也是 Helicone 支持任意业务维度打标的实现基础。3.3 请求体保持 Gemini 原生generateContent格式示例请求体完全遵循 Gemini REST API 规范{ contents: [ { role: user, parts: [{ text: List 3 classic sci-fi movies from the 1980s. }] } ], generationConfig: { temperature: 0.7, maxOutputTokens: 8192 } }contents对话内容数组role支持user/model多轮对话可追加多个元素parts内容块text即文本输入generationConfig生成参数示例给出temperature: 0.7采样温度与maxOutputTokens: 8192最大输出 token 数可按需增减。由于请求体没有被网关改写你在 Google 侧如何调 Gemini这里就如何写迁移成本几乎为零。3.4 响应解析按 Gemini 返回结构取文本响应 JSON 中生成文本位于candidates[0].content.parts[0].text示例中通过可选链安全取值第 79-80 行const responseText response.candidates?.[0]?.content?.parts?.[0]?.text || No response text;四、进阶方式用 Google 官方 SDK 走 Helicone 网关除了裸fetch仓库还提供了基于 Google 官方google/genaiSDK 的接入示例 gemini_example_sdk.ts。其思路是把网关地址注入 SDK 的httpOptionsimport { GoogleGenAI } from google/genai; const genAI new GoogleGenAI({ apiKey: GOOGLE_API_KEY, vertexai: true, httpOptions: { baseUrl: https://gateway.helicone.ai, headers: { Helicone-Auth: Bearer HELICONE_API_KEY, Helicone-Target-URL: https://generativelanguage.googleapis.com, }, }, }); async function generateContent() { const response await genAI.models.generateContent({ model: gemini-2.0-flash-001, contents: Why is the sky blue?, }); console.log(response.text); } generateContent();要点SDK 的apiKey仍然填 Google 的密钥或按你的鉴权方式配置httpOptions.baseUrl指向网关httpOptions.headers注入 Helicone 认证头与目标地址头注意此处使用了Helicone-Target-URL全大写 URL与 README 中的Helicone-Target-Url写法不同——网关在解析时通过this.headers.get(Helicone-Target-URL)读取第 359 行HTTP 头本身不区分大小写两种写法均被正确识别这种方式适合已经深度使用官方 SDK、希望最小改动的项目。五、多用户场景为什么要在请求里带 User ID仓库同名目录下的 Python 示例 examples/gemini-instructor-example/python 特意演示了带与不带user_id的对比两次请求在功能上完全一致但只有第二次会与用户test_user_123关联从而可以在 Helicone 控制台中按用户检索到它。这里有一个值得注意的客户端差异Google 官方 Python SDK 不支持在单次请求上动态传extra_headers必须把 Helicone 头放进default_metadata随客户端初始化见 python/README.md 的说明。因此多用户场景下要么为每个用户创建独立客户端实例要么在每次请求前重新配置客户端。而 TypeScript 的原生fetch方式没有这个限制——每个请求的头都是独立的天然适合多用户、动态打标的场景。六、在 Helicone 控制台验证请求运行示例后打开 Helicone 控制台检查以下几点请求列表中出现该条 Gemini 调用记录模型、耗时、token 消耗与成本已自动统计请求详情中能查看到user_id为test_user_123或你在.env中设置的值若在头中添加了Helicone-Property-*对应属性会出现在请求的自定义属性中可用于后续筛选与报表分析。七、常见问题排查现象排查方向401/认证失败检查HELICONE_API_KEY是否正确、是否以Bearer前缀发送上游返回 4xx确认GEMINI_API_KEY有效确认请求体符合 GeminigenerateContent规范请求超时或网络错误确认运行环境能访问gateway.helicone.ai若自托管检查HELICONE_URL指向的网关地址控制台查不到请求确认头字段名拼写无误尤其是Helicone-Auth与Helicone-Target-Url此外run.sh中内置了环境自检node/npm缺失或.env不存在时会在运行前给出明确报错可作为快速排错入口。八、总结本示例展示了接入 Helicone 网关最轻量的一条路径不改 Gemini 的请求协议只改 URL 主机与三个网关头即可让 Google Gemini 调用进入 Helicone 的可观测体系。无论你倾向裸fetch的透明可控、官方 SDK 的零成本迁移还是结合 Instructor 的结构化输出参考同目录 Python 示例核心原理一致——网关替你转发、记录、打标而你的业务代码始终保持简洁。更完整的网关能力统一 OpenAI 兼容 API、多 provider 路由、缓存、会话追踪等可继续阅读仓库中的 docs/gateway/overview.mdx 与 docs/gateway/integrations/overview.mdx网关头部的完整解析逻辑可深入 worker/src/lib/models/HeliconeHeaders.ts 查看。【免费下载链接】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），仅供参考