OpenAI Gemini 代理服务完全指南：从部署到扩展

2026-04-03 09:03:05作者：韦蓉瑛

项目价值：为什么选择 OpenAI Gemini 代理服务

还在为 AI 模型接口不兼容烦恼？OpenAI Gemini 代理服务提供了一站式解决方案，让开发者能够无缝衔接 Gemini 模型与 OpenAI API 生态。这个轻量级无服务器（Serverless）工具通过统一接口抽象，解决了多模型系统集成中的三大核心痛点：

协议转换：自动将 OpenAI API 请求格式转换为 Gemini 模型兼容格式
跨平台部署：支持 Node.js、Deno、Bun 等多种运行时环境
弹性扩展：适配 Vercel、Netlify 等 Serverless 平台，按需伸缩资源

无论是构建聊天机器人、开发 AI 助手，还是集成文本嵌入功能，本项目都能显著降低开发复杂度，让你专注于业务逻辑而非接口适配。

环境准备：3 分钟快速启动

系统环境检测脚本

在开始前，先确认你的开发环境是否满足基本要求。创建以下检测脚本并运行：

#!/bin/bash
# 环境检测脚本
echo "=== 系统环境检测 ==="
node -v || echo "❌ Node.js 未安装 (推荐 v16+)"
deno --version || echo "❌ Deno 未安装 (可选，推荐 v1.30+)"
bun --version || echo "❌ Bun 未安装 (可选，推荐 v1.0+)"
npm -v || echo "❌ npm 未安装"
echo "=== 网络检测 ==="
curl -s https://generativelanguage.googleapis.com/v1beta/models && echo "✅ Gemini API 网络可达" || echo "❌ 无法连接 Gemini API"

快速检查清单：

✅ Node.js v16 或更高版本
✅ npm 包管理器
✅ 网络可访问 Gemini API 服务
✅ 项目目录具有读写权限

项目安装与依赖管理

首先克隆项目代码库：

git clone https://gitcode.com/gh_mirrors/op/openai-gemini
cd openai-gemini

项目采用模块化依赖管理，核心依赖仅包含 @whatwg-node/server，安装过程非常轻量：

# 安装生产依赖
npm install

💡 技巧：如果需要在开发过程中实时监控文件变化并自动重启服务，可以安装开发依赖：

# 安装开发依赖（可选）
npm install --save-dev

核心模块解析：架构与工作原理

核心文件功能矩阵

文件路径	类型	功能描述	关键技术点
src/worker.mjs	核心逻辑	请求处理与协议转换	Fetch API、Stream 处理
api/handler.mjs	接口入口	Vercel Edge 函数入口	Vercel 边缘计算
netlify/edge-functions/handler.mjs	接口入口	Netlify 边缘函数入口	Netlify Edge 运行时
node.mjs	启动脚本	Node.js 环境启动入口	HTTP 服务器配置
deno.mjs	启动脚本	Deno 环境启动入口	Deno 权限管理
bun.mjs	启动脚本	Bun 环境启动入口	Bun 高性能运行时

请求处理流程解析

项目的核心功能是实现 OpenAI API 格式到 Gemini API 的转换，以下是完整的请求处理流程：

graph TD
    A[客户端请求] --> B{请求类型}
    B -->|OPTIONS| C[处理跨域预检]
    B -->|POST/GET| D[验证请求头与参数]
    D --> E{API 端点}
    E -->|/chat/completions| F[处理对话补全请求]
    E -->|/embeddings| G[处理嵌入生成请求]
    E -->|/models| H[处理模型列表请求]
    E -->|其他| I[返回 404 错误]
    F --> J[转换请求格式为 Gemini API]
    G --> J
    H --> J
    J --> K[调用 Gemini API]
    K --> L[转换响应格式为 OpenAI API]
    L --> M[返回响应给客户端]

🔍 重点：在 src/worker.mjs 中，fetch 函数是整个系统的入口点，它通过 URL 路径判断请求类型，并调用相应的处理函数（如 handleCompletions、handleEmbeddings 等）。

数据转换核心逻辑

请求转换是项目的核心功能，主要通过 transformRequest 函数实现。该函数完成以下关键转换：

消息格式转换：将 OpenAI 对话格式转换为 Gemini 内容格式
配置参数映射：将 OpenAI 参数（如 temperature、max_tokens）映射为 Gemini API 对应参数
工具调用适配：处理函数调用（Function Call）的格式转换

// 核心参数映射示例（src/worker.mjs 第 260-271 行）
const fieldsMap = {
  frequency_penalty: "frequencyPenalty",
  max_completion_tokens: "maxOutputTokens",
  max_tokens: "maxOutputTokens",
  n: "candidateCount",
  presence_penalty: "presencePenalty",
  seed: "seed",
  stop: "stopSequences",
  temperature: "temperature",
  top_k: "topK",
  top_p: "topP",
};

💡 技巧：如果需要添加自定义参数映射，可以扩展 fieldsMap 对象，并确保在 transformConfig 函数中正确处理。

实战应用：部署与使用指南

手动部署方案

根据你的运行时环境选择以下启动命令：

Node.js 环境：

# 启动生产环境
npm start

# 开发模式（文件变化自动重启）
npm run dev

Deno 环境：

# 启动生产环境
npm run start:deno

# 开发模式
npm run dev:deno

Bun 环境：

# 启动生产环境
npm run start:bun

# 开发模式
npm run dev:bun

启动成功后，服务默认监听本地 3000 端口，可通过 http://localhost:3000 访问。

⚠️ 警告：生产环境中必须设置适当的安全策略，限制 API 访问来源，避免未授权使用。

容器化部署方案

对于需要容器化部署的场景，可以使用以下 Dockerfile：

FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm install --production
COPY . .
EXPOSE 3000
CMD ["npm", "start"]

构建并运行容器：

docker build -t openai-gemini .
docker run -p 3000:3000 -d openai-gemini

快速检查清单：

✅ 服务启动后可通过 curl http://localhost:3000/models 验证
✅ 环境变量已正确配置（如需要）
✅ 防火墙规则允许 3000 端口访问
✅ 容器日志中无错误信息

基本使用示例

以下是使用 curl 调用代理服务的基本示例：

获取模型列表：

curl http://localhost:3000/models \
  -H "Authorization: Bearer YOUR_GEMINI_API_KEY"

创建对话补全：

curl http://localhost:3000/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_GEMINI_API_KEY" \
  -d '{
    "model": "gemini-flash-latest",
    "messages": [{"role": "user", "content": "Hello world"}]
  }'

生成文本嵌入：

curl http://localhost:3000/embeddings \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_GEMINI_API_KEY" \
  -d '{
    "input": "The quick brown fox jumps over the lazy dog",
    "model": "gemini-embedding-001"
  }'

模块扩展指南：自定义功能开发

添加自定义数据处理器

要扩展项目功能，例如添加自定义数据预处理逻辑，可以按照以下步骤进行：

创建处理器模块：在 src 目录下创建 processors 文件夹，并添加你的处理器文件，例如 src/processors/custom-processor.mjs：

// 自定义数据处理器示例
export const customProcessor = {
  name: "custom-processor",
  
  // 处理输入数据
  processInput: (input) => {
    // 添加自定义处理逻辑，如文本清洗、格式转换等
    return input.trim().replace(/\s+/g, ' ');
  },
  
  // 处理输出数据
  processOutput: (output) => {
    // 添加自定义输出处理逻辑
    return output;
  }
};

集成到请求处理流程：修改 src/worker.mjs 中的 handleCompletions 函数，在调用 Gemini API 前后应用处理器：

// 在文件顶部导入处理器
import { customProcessor } from './processors/custom-processor.mjs';

// 在 handleCompletions 函数中应用处理
async function handleCompletions (req, apiKey) {
  // ... 现有代码 ...
  
  // 处理输入数据
  req.messages = req.messages.map(msg => ({
    ...msg,
    content: customProcessor.processInput(msg.content)
  }));
  
  // ... 调用 Gemini API ...
  
  // 处理输出数据
  if (response.ok) {
    let body = await response.text();
    body = customProcessor.processOutput(body);
    // ... 后续处理 ...
  }
}

添加配置选项：修改请求转换逻辑，允许通过请求参数启用/禁用自定义处理器：

// 在 transformConfig 函数中添加处理器配置
const transformConfig = (req, isV3) => {
  // ... 现有代码 ...
  
  // 添加处理器配置
  if (req.processor) {
    cfg.processor = req.processor;
  }
  
  return cfg;
};

快速检查清单：

✅ 新处理器模块已正确导入
✅ 处理逻辑已集成到请求/响应流程
✅ 添加了必要的错误处理
✅ 通过测试验证新功能

常见问题：故障排除与优化

连接问题排查流程

当服务无法连接到 Gemini API 时，按照以下步骤排查：

检查网络连接：

curl -v https://generativelanguage.googleapis.com/v1beta/models

验证 API 密钥：确保提供的 API 密钥有效且具有适当权限
检查区域设置：Gemini API 在部分地区可能不可用，可在 api/handler.mjs 中调整区域配置：

// api/handler.mjs 第 11-31 行
export const config = {
  runtime: "edge",
  regions: [
    "arn1", "bom1", "cdg1", "cle1", "cpt1", 
    "dub1", "dxb1", "fra1", "gru1", "hnd1",
    "iad1", "icn1", "kix1", "lhr1", "pdx1",
    "sfo1", "sin1", "syd1"
  ],
};

性能优化配置

对于生产环境部署，建议进行以下优化：

设置合理的超时时间：在请求 Gemini API 时添加超时控制
启用响应缓存：对于重复请求，可添加缓存层减少 API 调用
调整并发设置：根据服务器资源调整并发请求处理数量

⚠️ 警告：缓存敏感数据时需确保符合数据隐私法规，避免存储个人身份信息。

错误处理最佳实践

在生产环境中，建议增强错误处理机制：

添加详细日志：记录请求/响应详情，便于问题排查
实现重试逻辑：对临时错误（如网络波动）添加自动重试
返回友好错误：将 Gemini API 错误转换为更易理解的提示信息

// 增强错误处理示例
const errHandler = (err) => {
  console.error(`[${new Date().toISOString()}] Error:`, err);
  const status = err.status ?? 500;
  const message = status === 401 
    ? "API 密钥无效或已过期" 
    : status === 429 
      ? "请求频率超限，请稍后再试" 
      : "服务暂时不可用，请稍后重试";
  return new Response(JSON.stringify({ error: { message } }), fixCors({ status }));
};