Helicone × Vertex AI Gemini Python 异步调用修复 generate_content_async 的 async REST 凭据问题【免费下载链接】helicone Open source LLM observability platform. One line of code to monitor, evaluate, and experiment. YC W23 项目地址: https://gitcode.com/GitHub_Trending/he/helicone本指南围绕开源 LLM 可观测平台 Helicone 仓库中的官方示例examples/vertex-gemini-example/python展开讲解在 Python 中使用 Vertex AI Gemini 模型并通过 Helicone 网关记录请求时generate_content_async报出 async REST 凭据缺失错误的根因与完整修复方案。读完本文你将掌握一套可直接复制运行的初始化模板理解aiplatform与vertexai双层初始化的差异并能结合 Helicone 网关源码理解helicone-target-url、helicone-auth等元数据头的转发机制。背景一条常见的 Google Cloud 报错信息当你按照 Helicone 官方文档docs/integrations/gemini/vertex/python.mdx完成vertexai.init()的代理配置后直接调用异步方法generate_content_async很可能遇到这样一段警告REST async clients requires async credentials set using aiplatform.initializer._set_async_rest_credentials(). Falling back to grpc since no async rest credentials were detected.含义拆解如下REST async clients requires async credentialsVertex AI 的异步客户端若走 REST 传输需要一组“异步专用”的凭据对象而不能复用同步凭据Falling back to grpcGoogle Cloud 库检测不到这组凭据后会自动降级到 gRPC 传输而降级到 gRPC 之后Helicone 网关通过 REST 端点捕获请求的机制就会失效导致日志记录链路中断或行为不符合预期。Helicone 的官方示例examples/vertex-gemini-example/python正是围绕这一痛点给出了一套经过验证的解决方案下文逐步展开。环境准备从零开始运行示例示例目录包含四个文件README.md、gemini_example.py、requirements.txt与run.sh。先完成环境搭建。1. 创建虚拟环境python -m venv venv source venv/bin/activate2. 安装依赖pip install -r requirements.txtrequirements.txt中对版本有明确约束examples/vertex-gemini-example/python/requirements.txtgoogle-cloud-aiplatform1.36.0 vertexai0.0.1 python-dotenv1.0.0 asyncio3.4.3 google-api-core[grpc,async_rest]2.21.0 google-auth[aiohttp]2.35.0其中两个依赖与本问题的解决方案直接相关google-api-core[grpc,async_rest]extra 标记async_rest会安装异步 REST 传输所需的额外依赖是_set_async_rest_credentials()能够生效的前提之一google-auth[aiohttp]异步凭据刷新依赖 aiohttp 客户端同时它也是示例末尾“Unclosed client session”警告的来源见后文已知问题一节。3. 配置环境变量示例通过python-dotenv加载.env文件需要填写三个变量HELICONE_API_KEYyour-helicone-api-key PROJECT_IDyour-gcp-project-id LOCATIONus-central1 # or your preferred regionHELICONE_API_KEY在 Helicone 控制台生成的 API Key用于向网关鉴权PROJECT_ID你的 Google Cloud 项目 IDLOCATION模型部署区域示例默认us-central1可按实际资源位置替换但需与后续helicone-target-url中拼接的区域保持一致。4. 配置 Google Cloud 应用默认凭据gcloud auth application-default login该命令会在本地写入 Application Default CredentialsADC供google.auth.default()在代码中无感读取。5. 运行示例python gemini_example.py仓库还附带了一键脚本 run.sh它会自动创建虚拟环境、安装依赖、检测gcloud是否安装、检查 ADC 是否已配置未配置则引导登录最后执行示例并退出虚拟环境适合在 CI 或全新机器上快速复现。问题根因异步 REST 传输缺少独立的凭据对象要理解修复方案需要先明白 Vertex AI Python 客户端的凭据体系。Google Cloud 库区分了两类凭据同步凭据即google.auth.default()返回的 ADC 凭据供同步请求如generate_content使用异步凭据供generate_content_async等异步请求使用在 REST 传输下必须显式注入否则库会输出上述警告并回退到 gRPC。Helicone 的代理方案基于 REST 网关转发api_endpointgateway.helicone.ai因此异步调用也必须走 REST 传输这就产生了“必须显式设置异步 REST 凭据”的硬性要求。示例的修复思路正是补齐这一环。解决方案五步修复异步 REST 凭据示例 gemini_example.py 给出了完整的修复链路可拆解为五步。第 1 步从 ADC 获取访问令牌credentials, _ google.auth.default() auth_req google.auth.transport.requests.Request() credentials.refresh(auth_req) token credentials.token先通过google.auth.default()拿到应用默认凭据再调用refresh()强制刷新从中取出当前有效的访问令牌token。注意必须显式 refresh未经刷新的凭据可能没有有效的token属性。第 2 步用令牌构造异步静态凭据from google.auth.aio.credentials import StaticCredentials async_credentials StaticCredentials(tokentoken)StaticCredentials是google.auth.aio命名空间下的异步凭据实现它不执行动态刷新而是直接持有给定的令牌适合短期运行的脚本场景。第 3 步显式初始化 aiplatform 并指定 REST 传输from google.cloud import aiplatform aiplatform.init( projectPROJECT_ID, locationLOCATION, api_transportrest # Explicitly set REST transport )这里初始化的是底层google.cloud.aiplatform注意与vertexai区分。api_transportrest是关键参数它把整个服务层固定为 REST 传输模式。第 4 步注入异步 REST 凭据aiplatform.initializer._set_async_rest_credentials(credentialsasync_credentials)aiplatform.initializer._set_async_rest_credentials()是一个带下划线前缀的内部 API用于把第 2 步构造的异步凭据注册到 aiplatform 的初始化器上。调用之后异步 REST 客户端才能获得所需的凭据不再触发“Falling back to grpc”警告。第 5 步通过 Helicone 网关初始化 vertexaiimport vertexai vertexai.init( projectPROJECT_ID, locationLOCATION, api_endpointgateway.helicone.ai, api_transportrest, request_metadata[ (helicone-target-url, fhttps://{LOCATION}-aiplatform.googleapis.com), (helicone-auth, fBearer {HELICONE_API_KEY}) ] )这一步是整个集成的心脏三个要素缺一不可api_endpointgateway.helicone.ai把 Vertex AI 的请求端点替换为 Helicone 网关使所有 Gemini 调用先流经网关再做转发与日志记录api_transportrest与底层 aiplatform 保持一致强制 REST 传输保证异步凭据注入真正生效request_metadata以 gRPC 元数据的形式注入两个 Helicone 定制头网关正是依靠它们完成路由与鉴权helicone-target-url声明真实的上游地址Vertex AI REST 端点https://{LOCATION}-aiplatform.googleapis.com网关会把请求转发到该地址helicone-auth携带Bearer {HELICONE_API_KEY}用于在网关侧完成 Helicone 鉴权。初始化完成后即可创建模型并异步生成内容model GenerativeModel( gemini-1.5-pro, generation_config{response_mime_type: application/json} ) response await model.generate_content_async(contents[Tell me a joke about programming]) print(response.text)元数据头如何被 Helicone 网关消费源码级验证request_metadata中注入的头并非“约定俗成”而是 Helicone 网关实际读取的协议字段。以网关核心实现 worker/src/lib/models/HeliconeHeaders.ts 为证其getHeliconeHeaders()方法显式解析了这两项return { heliconeAuth: this.headers.get(helicone-auth) ?? null, ... targetBaseUrl: this.headers.get(Helicone-Target-URL) ?? null, ... };helicone-auth被解析为heliconeAuth用于后续的请求鉴权Helicone-Target-URL被解析为targetBaseUrl即真实上游地址。随后网关路由器会对targetBaseUrl做合法性校验URL 格式、协议、域名是否在批准列表中等校验通过后把请求转发到目标服务同时完成请求/响应日志记录。整个过程可以概括为Vertex AI SDK │ api_endpoint gateway.helicone.ai │ request_metadata: helicone-target-url / helicone-auth ▼ Helicone Gateway (gateway.helicone.ai) │ 读取 Helicone-Target-URL → 校验目标地址 │ 读取 helicone-auth → 鉴权 │ 记录请求与响应日志 ▼ Vertex AI REST 端点 (https://{LOCATION}-aiplatform.googleapis.com)这也解释了为什么“必须先修复异步凭据”一旦异步请求降级到 gRPC请求不再经过网关的 REST 端点helicone-target-url与helicone-auth无从生效日志记录也就随之失效。已知问题Unclosed Client Session 警告运行示例时控制台可能出现以下警告Unclosed client session client_session: aiohttp.client.ClientSession object at 0x... Unclosed connector connections: [deque([(aiohttp.client_proto.ResponseHandler object at 0x..., ...)])] connector: aiohttp.connector.TCPConnector object at 0x...这是 Google Cloud 库内部使用的 aiohttp 异步客户端在程序退出前未显式关闭所致属于库层面的资源管理问题不影响示例功能与日志记录结果。示例源码在main()入口处通过以下方式抑制了ResourceWarning噪音if not sys.warnoptions: warnings.filterwarnings(ignore, categoryResourceWarning)官方文档明确说明在示例场景下可以安全忽略若进入生产环境则应自行实现连接池与客户端的优雅关闭例如在应用退出钩子中调用aiohttp.ClientSession.close()避免长生命周期服务中的连接泄漏。进阶需要精细控制时的 Manual Logger 方案如果应用对日志内容有更高要求例如同时处理异步与流式响应、需要自定义元数据、控制日志上报时机官方文档 docs/integrations/gemini/vertex/python.mdx 还提供了 Helicone Manual Logger 的替代方案引入HeliconeManualLogger通过new_builder(request)构造日志构建器调用add_model()记录模型名add_response()记录完整响应add_chunk()逐块记录流式响应最后在finally中调用await log_builder.send_log()上报到https://api.helicone.ai/v1/log请求体以provider: vertex标识来源。该方案不依赖网关转发而是由业务代码主动上报请求/响应适合流式输出、需要精确控制日志粒度或网关方案不便落地的复杂场景其优势在于对异步与流式响应的原生支持以及对日志内容与上报时机的完全掌控。小结本文以 Helicone 仓库官方示例为核心完整梳理了 Vertex AI Gemini 异步调用接入 Helicone 的修复链路报错根因是异步 REST 客户端缺少独立凭据导致降级到 gRPC破坏网关转发修复关键在aiplatform.initializer._set_async_rest_credentials()StaticCredentials 双层api_transportrest的配合request_metadata注入的helicone-target-url与helicone-auth是网关路由与鉴权的协议字段可在 HeliconeHeaders.ts 的源码中直接验证示例附带的一键脚本 run.sh 与完整依赖清单 requirements.txt 可帮助你快速复现官方集成文档 docs/integrations/gemini/vertex/python.mdx 则提供了 Manual Logger 等进阶用法供生产环境参考。【免费下载链接】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），仅供参考
