1. 项目概述在Google Cloud上搭建你自己的OpenAI兼容API网关如果你正在寻找一种方法能够让你手头那些原本为OpenAI ChatGPT设计的应用无缝对接上Google Cloud Vertex AI的强大模型比如Gemini Pro、PaLM 2或者Codey那么这个项目就是你一直在找的“桥梁”。简单来说它是一个部署在Google Cloud Run上的服务能够将标准的OpenAI API请求格式实时翻译并转发给Vertex AI的后端让你的应用以为自己在和OpenAI对话实际上却是在调用Google的模型。这个想法的精妙之处在于它解决了生态兼容性的痛点。如今大量优秀的开源项目、开发工具如VSCode插件和客户端如Chatbot UI都原生支持OpenAI API协议。通过这个兼容层你无需重写这些应用的任何代码就能让它们立刻获得使用Gemini等模型的能力。无论是想用Chatbot UI搭建一个私有的Gemini聊天前端还是想在VSCode里直接通过侧边栏调用Codey来辅助编程这个项目都能帮你快速实现。它本质上是一个轻量级的、可自托管的API代理特别适合开发者、技术团队以及对数据隐私和模型选择有自定义需求的用户。2. 核心架构与工作原理拆解2.1 为什么需要这样一个兼容层在AI应用开发中API协议就像一种“通用语言”。OpenAI的Chat Completions API由于其先发优势和广泛的开发者采纳已经成为许多应用事实上的标准接口。然而云服务商提供的模型各有千秋Google Vertex AI在特定任务、成本或多模态支持上可能具有优势。直接切换API意味着要对现有应用进行大量重构。这个项目的核心价值就在于提供了“协议转换”功能。它接收符合OpenAI API规范的HTTP请求包括相同的端点路径、请求头、JSON数据结构然后在内部将其映射为Vertex AI SDK所能理解的调用方式。这样一来前端应用保持不变后端模型可以灵活切换或并行使用极大地提升了技术栈的灵活性和可维护性。2.2 技术栈选型与设计考量项目采用Python作为开发语言这是一个非常务实的选择。Python在AI和Web开发领域拥有最丰富的库生态。其主体框架基于FastAPI这是一个现代、高性能的Web框架特别适合构建API。FastAPI能自动生成OpenAPI文档与OpenAI API的文档化特性天然契合也便于开发者调试和验证。对于模型调用层项目使用了LangChain。这是一个高阶的抽象库它封装了不同AI提供商包括Vertex AI的SDK提供统一的接口。使用LangChain的好处是如果未来需要增加对更多模型的支持例如在同一个服务内同时支持Vertex AI和另一种本地模型代码的改动可以降到最低主要工作在于添加新的LangChain集成模块。整个服务被设计为无状态的、可水平扩展的容器化应用完美契合Google Cloud Run的Serverless特性。这意味着你无需管理服务器服务会根据流量自动缩放并且只为实际使用的计算资源付费。2.3 数据流与核心转换逻辑理解数据如何在系统中流动是掌握这个项目的关键。当一个客户端比如Chatbot UI发起请求时完整的流程如下请求接收客户端向https://your-service.a.run.app/v1/chat/completions发送一个POST请求其Body格式与调用OpenAI官方API完全一致例如包含model,messages,temperature等字段。请求验证与解析FastAPI应用接收到请求首先验证Authorization头中的API密钥此密钥由你在部署时设定用于保护你的端点。随后解析JSON体提取出关键参数。参数映射与转换这是核心步骤。应用将OpenAI格式的参数映射到Vertex AI模型所需的参数上。messages列表中的对话历史会被转换为LangChainChatPromptTemplate所能处理的格式。model字段在本服务中实际上是一个“路由标识”。虽然客户端可能发送gpt-3.5-turbo但服务端会忽略此值转而使用环境变量MODEL_NAME如gemini-pro来决定实际调用的Vertex AI模型。temperature,max_tokens(映射为MAX_OUTPUT_TOKENS),top_p等参数则直接传递给Vertex AI的模型调用。模型调用通过LangChain的ChatVertexAI类初始化一个聊天模型实例并传入映射后的参数向Vertex AI服务发起同步调用。响应格式化收到Vertex AI的回复后服务需要将回复包装成OpenAI API标准的响应格式。这包括生成一个符合OpenAI规范的id通常是随机字符串计算usage本项目目前返回0实际可考虑估算并将模型回复内容放入choices[0].message.content中。响应返回将格式化后的JSON通过HTTP响应返回给客户端。客户端完全感知不到后端的模型已经切换实现了无缝对接。注意这个转换过程并非百分百无损。OpenAI和Vertex AI的模型在能力、上下文长度、参数细微含义上可能存在差异。例如某些高级的OpenAI API功能如function calling可能没有直接的Vertex AI对应项。本项目的目标是覆盖最核心、最常用的聊天补全功能。3. 从零开始本地开发与环境搭建在将服务部署到云端之前强烈建议先在本地完成环境搭建和测试。这能帮助你快速理解项目结构并进行自定义修改。3.1 前期准备与工具安装首先你需要准备好以下工具Python 3.11 或 3.12项目明确支持这两个版本。注意文档提到Python 3.12.4因依赖库Pydantic的某个问题可能存在兼容性问题建议使用3.12.3或3.11.x稳定版。Google Cloud CLI (gcloud)这是与Google Cloud服务交互的命令行工具。你需要用它来认证和设置项目。Git用于克隆项目代码库。安装Google Cloud CLI后在终端运行gcloud init来完成初始的登录和项目配置。如果你已经有多个项目记得选择或创建你想要用于测试的那个项目。3.2 克隆项目与虚拟环境配置从GitHub获取项目代码尽管项目已归档但代码完全可用git clone https://github.com/Cyclenerd/google-cloud-gcp-openai-api.git cd google-cloud-gcp-openai-api接下来创建一个独立的Python虚拟环境。这是Python开发的最佳实践可以避免不同项目间的依赖冲突。python3 -m venv .venv激活虚拟环境在Linux/macOS上source .venv/bin/activate在Windows上.venv\Scripts\activate激活后你的命令行提示符前通常会显示(.venv)表示已进入虚拟环境。3.3 依赖安装与本地认证在虚拟环境激活的状态下安装项目所需的所有Python包pip install -r requirements.txt这个requirements.txt文件包含了FastAPI、LangChain、Google Cloud Vertex AI SDK等核心依赖。要让本地应用能够访问你的Google Cloud项目资源需要进行应用默认凭据认证gcloud auth application-default login这个命令会打开浏览器让你登录Google账号并授权。完成后本地环境就具备了调用Vertex AI API的权限。你还需要设置默认的配额项目确保API调用能正确计费gcloud auth application-default set-quota-project [你的项目ID]3.4 启动本地服务并进行测试现在你可以启动本地开发服务器了。在启动前我们需要设置几个关键的环境变量export DEBUGTrue # 开启调试日志方便查看请求和响应的详细信息 export OPENAI_API_KEYsk-your-test-key-here # 设置一个自定义的API密钥用于客户端认证 export MODEL_NAMEgemini-pro # 指定要使用的Vertex AI模型例如Gemini Pro在Windows PowerShell中使用set命令替代export。然后使用Uvicorn一个快速的ASGI服务器启动应用uvicorn vertex:app --reload--reload参数使得在修改代码后服务器会自动重启非常适合开发。服务启动后默认监听在http://localhost:8000。你可以立即用curl命令进行测试curl --location http://localhost:8000/v1/chat/completions \ --header Content-Type: application/json \ --header Authorization: Bearer sk-your-test-key-here \ --data { model: gpt-3.5-turbo, messages: [ { role: user, content: 用中文介绍一下你自己 } ] }如果一切正常你将收到一个JSON格式的回复内容来自Gemini Pro模型但格式完全符合OpenAI API规范。通过查看终端输出的调试信息因为DEBUGTrue你可以清晰地看到请求被接收、转换和响应的全过程。实操心得在本地调试时务必关注DEBUG日志。它能帮你确认参数是否正确映射以及Vertex AI是否返回了错误。常见的初期错误包括认证失败gcloud auth未做、项目未启用Vertex AI API、或者请求的区域GOOGLE_CLOUD_LOCATION不支持你所选的模型。4. 部署实战将服务发布到Google Cloud Run本地测试通过后就可以将服务部署到生产环境了。Google Cloud Run是一个完全托管的Serverless计算平台能自动扩缩容是我们这个API网关的理想宿主。4.1 部署前的权限与配置检查部署脚本deploy.sh会帮你完成大部分工作但前提是你的Google Cloud账号有足够的权限。为了部署过程顺畅建议给你当前用于部署的用户通常是你的个人账号分配项目的“所有者”角色。这虽然权限较大但能避免因权限不足导致的构建或部署失败。另一个关键权限是给默认的计算服务账号添加“Vertex AI 用户”角色。Cloud Run服务在运行时会使用一个名为[PROJECT_NUMBER]-computedeveloper.gserviceaccount.com的服务账号来代表自己执行操作。这个账号需要有权调用Vertex AI API。 你可以通过Google Cloud控制台IAM与管理 - IAM找到这个服务账号并为其添加roles/aiplatform.user角色。4.2 执行一键部署脚本部署过程非常简单。确保你已通过gcloud auth login登录并通过gcloud config set project [PROJECT_ID]设置了默认项目。你可以直接运行脚本进行部署bash deploy.sh这个脚本会依次执行以下操作基于项目根目录的Dockerfile构建容器镜像。将镜像推送到Google Cloud Artifact Registry容器仓库。在Cloud Run上创建或更新一个服务使用刚推送的镜像。将服务配置为允许“未经验证的调用”即公开访问这样任何知道URL和API密钥的人都可以调用它。注意在生产环境中你可能需要结合Cloud IAP或API网关来增加一层安全控制。脚本运行成功后终端会输出服务的URL格式类似于https://openai-api-vertex-xxxxxx-xx.a.run.app。这个URL就是你的OpenAI兼容API网关的地址。4.3 自定义部署参数部署脚本支持通过环境变量进行自定义OPENAI_API_KEY你可以指定一个自定义的API密钥而不是使用脚本随机生成的。例如export OPENAI_API_KEYsk-my-secure-key-123。GOOGLE_CLOUD_LOCATION选择部署Cloud Run服务的区域这会影响服务的网络延迟。例如export GOOGLE_CLOUD_LOCATIONasia-northeast1东京。设置好环境变量后再运行bash deploy.sh即可。4.4 验证云端部署部署完成后使用curl命令测试你的云端端点只需将之前本地测试命令中的localhost:8000替换为你的Cloud Run URL即可curl --location https://your-cloud-run-url.a.run.app/v1/chat/completions \ --header Authorization: Bearer sk-your-api-key \ ...如果返回成功的JSON响应恭喜你你的私有OpenAI兼容API网关已经正式上线了注意事项Cloud Run服务在无流量一段时间后会缩容到零实例这意味着下一个请求会遭遇“冷启动”延迟可能需要几秒钟来初始化容器。对于需要低延迟响应的生产场景你可以考虑配置“最小实例数”为1让至少一个实例始终保持运行但这会产生持续的计算费用。你需要根据实际流量模式和成本预算来权衡。5. 生态集成让现有应用无缝接入部署好API网关后最激动人心的部分就是将它与你喜爱的工具集成起来。由于它完美兼容OpenAI API集成工作通常只是修改一个配置项那么简单。5.1 集成Chatbot UI自托管聊天前端Chatbot UI 是一个功能丰富、界面优雅的开源ChatGPT风格前端。项目提供了chatbot-ui.sh脚本可以一键将其部署到Cloud Run。在运行脚本前需要设置两个环境变量export OPENAI_API_KEYsk-your-api-key # 必须与API网关部署时使用的密钥一致 export OPENAI_API_HOSThttps://your-api-gateway-url.a.run.app # 你的API网关地址**不要**在后面加 /v1然后运行脚本bash chatbot-ui.sh脚本会构建Chatbot UI的镜像并部署为另一个独立的Cloud Run服务。部署完成后你会获得一个前端网址。在Chatbot UI的设置中它已经配置为使用你提供的OPENAI_API_HOST和OPENAI_API_KEY。打开网页你就可以开始与背后的Gemini或PaLM 2模型对话了。5.2 集成VSCode OpenAI扩展VSCode OpenAI扩展 允许你在编辑器侧边栏直接与AI对话。配置步骤如下在VSCode中安装该扩展。点击VSCode左下角状态栏的扩展图标或在命令面板运行vscode-openai.configuration.show.quickpick。在配置向导中选择服务提供商为openai.com。当它要求输入API Base URL时填入你的Cloud Run网关地址并务必在末尾加上/v1例如https://your-api-gateway-url.a.run.app/v1。输入你设置的API密钥。配置完成后你就可以在VSCode中直接调用Vertex AI模型来解答编程问题、审查代码或生成注释了。5.3 集成其他基于OpenAI库的应用对于任何使用官方openaiPython库或Node.js库的应用程序集成方式通常是设置OPENAI_API_BASE环境变量。export OPENAI_API_BASEhttps://your-api-gateway-url.a.run.app/v1 export OPENAI_API_KEYsk-your-api-key python your_script.py在你的代码中openai.api_base会被这个环境变量覆盖所有对openai.ChatCompletion.create()的调用都会自动路由到你的Vertex AI网关。5.4 配置管理与环境变量详解服务的所有行为都通过环境变量控制无论是在本地运行还是在Cloud Run上。理解这些变量至关重要变量名默认值描述与实操建议DEBUGFalse设为True时输出详细日志生产环境务必设为False。GOOGLE_CLOUD_LOCATIONus-central1Vertex AI API调用的区域。必须是你项目已启用且目标模型可用的区域如europe-west1比利时、asia-northeast1东京。MODEL_NAMEchat-bison指定使用的Vertex AI模型。可选值包括chat-bison(PaLM 2 for Chat),codechat-bison(Codey),gemini-pro。确保你指定的模型在所选区域可用。MAX_OUTPUT_TOKENS512模型生成内容的最大token数。可通过客户端请求中的max_tokens参数覆盖。对于长文生成可以适当调高。TEMPERATURE0.2控制输出的随机性0.0-1.0。值越低输出越确定、保守值越高越有创造性。可通过客户端请求覆盖。OPENAI_API_KEY随机生成用于保护你的API端点的密钥。强烈建议在部署时设置为一个强密码这是防止他人滥用的主要手段。在Cloud Run控制台中你可以随时修改这些环境变量并重新部署无需改动代码。6. 高级配置、问题排查与性能调优6.1 模型参数调优与高级设置除了基础的环境变量你还可以通过修改代码来利用Vertex AI模型的更多高级参数。例如在vertex.py文件中找到初始化ChatVertexAI模型的地方你可以添加更多LangChain支持的参数。# 示例在模型初始化时添加更多控制参数 chat ChatVertexAI( model_namemodel_name, temperaturetemperature, max_output_tokensmax_output_tokens, top_ptop_p, top_ktop_k, # 控制采样池的大小 locationgoogle_cloud_location, projectgoogle_cloud_project_id, # 可以尝试添加以下参数需查阅LangChain和Vertex AI文档确认支持性 # stop_sequences[\n\n], # 定义停止序列 # candidate_count1, # 生成多少个候选回复 )重要提示任何对vertex.py的修改都需要重新构建Docker镜像并部署到Cloud Run才能生效。6.2 常见部署与运行问题排查在部署和使用过程中你可能会遇到一些典型问题。下面是一个快速排查指南问题现象可能原因解决方案部署失败提示“权限不足”1. 部署用户缺少权限。2. 默认计算服务账号缺少Vertex AI权限。1. 为部署用户添加“所有者”或“Cloud Run管理员”“Artifact Registry写入者”等角色。2. 为[PROJECT_NUMBER]-computedeveloper.gserviceaccount.com添加roles/aiplatform.user角色。API调用返回401 Unauthorized1. 请求头中未携带Authorization。2. API密钥错误。1. 确保请求头格式为Authorization: Bearer sk-your-key。2. 检查Cloud Run服务中设置的OPENAI_API_KEY环境变量确保客户端使用的密钥与之完全一致。API调用返回404 Not Found请求的URL路径错误。OpenAI兼容端点位于/v1/chat/completions。确保你的请求地址是https://[YOUR_URL]/v1/chat/completions。API调用返回5xx错误如500, 5031. 服务内部代码错误。2. Vertex AI服务不可用或配额用尽。3. Cloud Run实例冷启动或资源不足。1. 检查Cloud Run的日志Google Cloud控制台 - Cloud Run - 服务 - 日志。2. 确保Vertex AI API已在项目中启用且所在区域可用。3. 检查是否触发了模型的输入/输出长度限制。开启DEBUG模式查看详细错误。响应速度很慢首次调用Cloud Run冷启动。容器需要从零开始初始化。考虑配置“最小实例数”为1使服务至少保持一个常驻实例消除冷启动。但这会产生持续费用。模型输出不符合预期胡言乱语或格式错误1.temperature参数设置过高。2. 提示词Prompt格式问题。3. 模型本身对复杂指令的理解有限。1. 尝试降低temperature如设为0.1。2. 检查客户端发送的messages格式是否符合OpenAI标准。3. 尝试更清晰、结构化的指令。不同模型对提示词的敏感度不同。6.3 监控、日志与成本管理监控在Google Cloud控制台的Cloud Run服务详情页你可以看到请求数量、延迟、错误率等关键指标。设置告警策略当错误率飙升或延迟增加时接收通知。日志所有标准输出包括DEBUG日志都会自动收集到Cloud Logging中。通过查询日志你可以分析每一个API请求和响应对于调试复杂问题至关重要。成本管理成本主要来自两部分Cloud Run根据请求处理时消耗的CPU和内存资源以及实例运行时间计费。配置合理的CPU和内存限制在Dockerfile或Cloud Run服务设置中避免过度配置。Vertex AI根据模型调用次数和处理的token数量计费。务必在Google Cloud控制台的“配额”页面为Vertex AI API设置预算提醒防止意外费用产生。6.4 安全加固建议当前部署为了简便允许“未经验证的调用”。对于内部或公开服务建议增加安全层API密钥这是第一道防线务必使用强密钥。Google Cloud IAP为Cloud Run服务启用Identity-Aware Proxy可以要求用户使用Google账号登录才能访问。API网关使用Google Cloud API Gateway管理你的端点它可以提供速率限制、API密钥验证、监控等更多功能。私有网络将Cloud Run服务部署到VPC网络内部并仅通过内部负载均衡器或Cloud VPN访问彻底隔绝公网。这个项目提供了一个强大而灵活的起点让你能够将Google Cloud的AI能力快速融入现有生态。虽然原仓库已归档但其代码结构清晰基于FastAPI和LangChain构建使得根据自身需求进行二次开发例如增加对/v1/embeddings端点的支持或集成更多模型变得非常可行。最关键的是它验证了通过协议兼容层来解耦应用与模型供应商这一思路的可行性为构建更开放、可互操作的AI应用架构提供了实用参考。