OpenAI Gemini 开源项目全功能指南

一、核心价值解析

1.1 跨平台API代理解决方案

OpenAI Gemini项目是一个轻量级的Serverless代理服务，它创新性地解决了Gemini API与OpenAI接口规范不兼容的问题。通过该项目，开发者可以直接使用现有的OpenAI客户端代码与Google Gemini模型进行交互，无需大规模重构代码。这种兼容性层设计极大降低了AI模型迁移成本，为多模型部署提供了灵活选择。

1.2 多环境部署支持

项目提供了完整的跨环境运行方案，支持Node.js、Deno和Bun三种JavaScript运行时环境。这种设计确保了项目可以无缝集成到各种现有开发和生产环境中，无论是传统服务器部署还是现代无服务器架构，都能找到合适的运行方式。

1.3 功能完整性保障

项目实现了OpenAI API的核心功能映射，包括聊天补全（chat/completions）、嵌入（embeddings）和模型列表（models）等端点。通过精心设计的请求转换逻辑，确保了Gemini模型能力的完整呈现，同时保持与OpenAI API的高度兼容性。

📌 核心要点

• 实现Gemini API到OpenAI规范的无缝转换
• 支持Node.js、Deno和Bun三种运行时环境
• 完整实现聊天补全、嵌入生成等核心AI功能
• 轻量级设计，适合Serverless部署场景

二、环境准备指南

2.1 开发环境检测

在开始使用项目前，需要确保开发环境满足基本要求。执行以下命令检查系统配置：

# 检查Node.js版本 (v14+ 推荐)
node -v

# 检查npm版本
npm -v

# 检查Git版本
git --version

如未安装Node.js环境，建议使用nvm（Node Version Manager）进行安装和版本管理：

# 安装nvm (Linux/Mac)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.3/install.sh | bash

# 安装Node.js
nvm install 18
nvm use 18

2.2 项目获取与依赖安装

获取项目代码并安装必要依赖：

# 克隆项目仓库
git clone https://gitcode.com/gh_mirrors/op/openai-gemini

# 进入项目目录
cd openai-gemini

# 安装依赖包
npm install

项目依赖非常精简，仅包含一个核心依赖@whatwg-node/server，用于实现跨运行时的HTTP服务器功能。

2.3 环境变量配置

创建必要的环境变量文件，项目支持以下关键配置：

# 创建环境变量文件
touch .env

# 编辑.env文件，添加以下内容
PORT=8080
NODE_ENV=development

主要环境变量说明：

• PORT: 服务监听端口，默认为8080
• NODE_ENV: 运行环境，可选值为development或production

📌 核心要点

• 开发环境需要Node.js v14+、npm和Git
• 项目依赖极简，安装过程快速高效
• 通过环境变量控制服务端口和运行模式
• 支持多种运行时环境，可根据需求选择

三、功能模块详解

3.1 请求处理核心

项目的核心请求处理逻辑位于src/worker.mjs文件中，采用了模块化设计，主要包含以下功能：

1. CORS处理：实现跨域资源共享支持，确保API可以被前端应用安全调用
2. 请求路由：根据URL路径分发不同类型的API请求到相应处理函数
3. 错误处理：统一的错误捕获和响应机制，确保服务稳定性

关键代码片段：

// 请求路由处理
switch (true) {
  case pathname.endsWith("/chat/completions"):
    assert(request.method === "POST");
    return handleCompletions(await request.json(), apiKey)
      .catch(errHandler);
  case pathname.endsWith("/embeddings"):
    assert(request.method === "POST");
    return handleEmbeddings(await request.json(), apiKey)
      .catch(errHandler);
  case pathname.endsWith("/models"):
    assert(request.method === "GET");
    return handleModels(apiKey)
      .catch(errHandler);
  default:
    throw new HttpError("404 Not Found", 404);
}

3.2 模型适配层

项目实现了OpenAI API请求格式到Gemini API的转换逻辑，主要包括：

1. 请求转换：将OpenAI风格的请求参数转换为Gemini API需要的格式
2. 响应转换：将Gemini API返回的结果转换为OpenAI规范的响应格式
3. 模型映射：处理不同模型名称的映射关系，确保兼容性

请求转换核心函数：

// 请求转换主函数
const transformRequest = async (req, isV3) => ({
  ...await transformMessages(req.messages),
  safetySettings,
  generationConfig: transformConfig(req, isV3),
  ...transformTools(req),
});

3.3 多运行时支持

项目提供了针对不同JavaScript运行时的启动脚本：

1. Node.js支持：通过node.mjs实现标准Node.js环境运行
2. Deno支持：通过deno.mjs实现Deno环境运行
3. Bun支持：通过bun.mjs实现Bun环境运行

Node.js启动代码示例：

import { createServerAdapter } from "@whatwg-node/server";
import { createServer } from "node:http";
import worker from "./src/worker.mjs";

const port = +(process.env.PORT || 8080);

const serverAdapter = createServerAdapter(worker.fetch);
const server = createServer(serverAdapter);
server.listen(port, () => {
  console.log("Listening on:", server.address());
});

📌 核心要点

• 请求处理核心实现了路由分发和错误处理
• 模型适配层确保OpenAI API格式与Gemini API的兼容
• 多运行时支持满足不同部署环境需求
• 模块化设计确保代码可维护性和可扩展性

四、实战应用指南

4.1 快速启动服务

根据不同的运行时环境，选择相应的启动命令：

# Node.js环境
npm start

# Node.js开发模式（自动重启）
npm run dev

# Deno环境
npm run start:deno

# Deno开发模式
npm run dev:deno

# Bun环境
npm run start:bun

# Bun开发模式
npm run dev:bun

启动成功后，服务将默认在本地8080端口运行，可通过http://localhost:8080访问。

4.2 API调用示例

使用curl测试API功能：

1. 获取模型列表

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

2. 聊天补全

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

3. 生成嵌入

curl http://localhost:8080/v1/embeddings \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_GEMINI_API_KEY" \
  -d '{
    "input": "The food was delicious and the service was wonderful",
    "model": "gemini-embedding-001"
  }'

4.3 参数调优实战

以下是关键参数的调优指南，可根据具体需求调整：

参数名	默认值	推荐值	作用说明
temperature	0.7	0.5-0.9	控制输出随机性，值越高生成内容越多样
max_tokens	1024	512-2048	控制最大输出 tokens 数
top_p	1	0.9	核采样参数，控制输出多样性
presence_penalty	0	0-1	减少重复内容的惩罚系数
frequency_penalty	0	0-1	减少高频词出现的惩罚系数

参数调整示例：

{
  "model": "gemini-pro",
  "messages": [{"role": "user", "content": "写一篇关于AI的短文"}],
  "temperature": 0.8,
  "max_tokens": 1500,
  "top_p": 0.9,
  "presence_penalty": 0.3
}

4.4 常见问题排查

问题排查流程：

1. 检查服务状态

   • 确认服务是否正在运行
   • 检查服务日志是否有错误信息

2. 验证API密钥

   • 确保提供了有效的Gemini API密钥
   • 检查密钥是否具有足够的权限

3. 检查请求格式

   • 验证请求JSON格式是否正确
   • 确认使用了正确的API端点

4. 网络排查

   • 检查网络连接是否正常
   • 确认防火墙设置是否允许请求通过

5. 查看错误响应

   • 分析API返回的错误代码和消息
   • 根据错误提示调整请求参数

常见错误及解决方法：

• 401 Unauthorized：API密钥无效或未提供
• 404 Not Found：请求了不存在的API端点
• 429 Too Many Requests：API调用频率超限，需降低请求频率
• 500 Internal Server Error：服务内部错误，查看服务日志获取详细信息

📌 核心要点

• 提供多种运行环境的启动命令
• API调用格式与OpenAI规范兼容
• 参数调优可显著影响模型输出质量
• 遵循排查流程可快速定位和解决问题