docs: 更新README文件，优化格式和内容结构
- 为README添加更美观的Markdown格式和emoji图标 - 优化项目描述，突出核心功能和优势 - 重新组织安装和使用说明，使其更清晰易读 - 添加特殊用法和进阶技巧章节 - 同步更新中英文文档保持一致
This commit is contained in:
hex2077
parent
61c7d362da
commit
0e799798bc
2 changed files with 257 additions and 177 deletions
220
README-EN.md
220
README-EN.md
|
|
@ -1,167 +1,207 @@
|
|||
# GeminiCli2API
|
||||
<div align="center">
|
||||
This project contains two Node.js HTTP servers. They act as local proxies for the Google Cloud Code Assist API. One of the servers also provides an OpenAI API compatible interface. This allows you to bypass the terminal interface and integrate with any client through an API.
|
||||
|
||||
[中文](./README.md) / [English](./README-EN.md)
|
||||
# GeminiCli2API 🚀
|
||||
|
||||
**A powerful proxy that wraps the Google Gemini CLI into a local API, providing an OpenAI-compatible interface.**
|
||||
|
||||
</div>
|
||||
|
||||
## Project Overview
|
||||
<div align="center">
|
||||
|
||||
- `gemini-api-server.js`: This is a standalone Node.js HTTP server. It acts as a local proxy for the Google Cloud Code Assist API. This server provides all features and bug fixes. It is designed to be robust and flexible. With a fully controllable logging system, it is easy to monitor.
|
||||
- `openai-api-server.js`: This script is based on `gemini-api-server.js`. It creates a standalone Node.js HTTP server. This server is also a local proxy for the Google Cloud Code Assist API. However, it provides an OpenAI API compatible interface. Therefore, any client that supports the OpenAI API can use it directly.
|
||||
- `gemini-core.js`: This file contains the core logic shared by both servers. For example, authentication, API calls, request/response handling, and logging functions.
|
||||
[](https://www.gnu.org/licenses/gpl-3.0)
|
||||
[](https://nodejs.org/)
|
||||
|
||||
## Feature Description
|
||||
[**中文**](./README.md) | [**English**](./README-EN.md)
|
||||
|
||||
### Problems Solved
|
||||
</div>
|
||||
|
||||
- Solves the problem of reduced free quotas for the official Gemini API. Now, users can authorize with their Gemini CLI account to make 1000 requests per day.
|
||||
- Provides compatibility with the OpenAI API, making it convenient for existing OpenAI clients to use.
|
||||
> `GeminiCli2API` includes two independent Node.js HTTP servers that act as local proxies for the Google Cloud Code Assist API. One of these servers also provides an interface fully compatible with the OpenAI API. This allows you to break free from the terminal interface and easily integrate Gemini's powerful capabilities into any of your favorite clients or applications in API form.
|
||||
|
||||
### Current Limitations
|
||||
---
|
||||
|
||||
- Cannot use the built-in functions of the original Gemini CLI.
|
||||
- Does not support multimodal capabilities. (todo)
|
||||
## 📝 Project Overview
|
||||
|
||||
## Main Features
|
||||
This project consists of three core files, each with its own specific function:
|
||||
|
||||
### Gemini API Server (`gemini-api-server.js`)
|
||||
* `gemini-api-server.js`: 💎 **Native Gemini Proxy Service**
|
||||
* An independent Node.js HTTP server that acts as a local proxy for the Google Cloud Code Assist API.
|
||||
* It provides all core functionalities and bug fixes, designed to be robust, flexible, and equipped with a fully controllable logging system for easy monitoring and debugging.
|
||||
|
||||
- **Automatic Authentication and Token Renewal**: On the first run, the script guides the user to complete Google account manual authorization through a browser. It will obtain an OAuth token. This token is securely stored locally and automatically refreshed before it expires. This ensures the continuous operation of the service without manual intervention.
|
||||
- **Manual Authorization Flow**:
|
||||
1. **Copy Authorization Link**: The terminal will output a Google authorization URL. Please copy this URL.
|
||||
2. **Open the Link in a Browser**: Open the URL in a browser on any device with a graphical interface (e.g., your local computer).
|
||||
3. **Complete Authorization**: Log in to your Google account and grant permissions.
|
||||
4. **Copy the Redirected URL**: After authorization, the browser will attempt to redirect to a URL, extract the authorization code, complete authentication, and start the service normally.
|
||||
- **Flexible API Key Validation**: Users can provide the key in the URL query parameter (`?key=...`) or the `x-goog-api-key` request header. As long as the key is correct, the request can be authorized. The key can be set via the `--api-key` startup parameter.
|
||||
- **Role Normalization Fix**: The server automatically adds the necessary 'user'/'model' roles to the request body. At the same time, it correctly preserves `systemInstruction` (or `system_instruction`).
|
||||
- **Fixed Model List**: The server specifically provides and uses the `gemini-1.5-pro-latest` and `gemini-1.5-flash-latest` models.
|
||||
- **Full Gemini API Endpoint Support**: Implements `listModels`, `generateContent`, `streamGenerateContent`.
|
||||
- **Fully Controllable Logging System**: Includes the remaining validity period of the token. It can output timestamped prompt logs to the console or a file. Supports log printing.
|
||||
* `openai-api-server.js`: 🔄 **OpenAI Compatible Proxy Service**
|
||||
* Built on top of `gemini-api-server.js`, it also acts as a proxy for the Google API.
|
||||
* Crucially, it exposes an interface compatible with the OpenAI API. This means any client that supports the OpenAI API can switch to use it seamlessly without any code modification.
|
||||
|
||||
### OpenAI Compatible API Server (`openai-api-server.js`)
|
||||
* `gemini-core.js`: ⚙️ **Core Shared Logic**
|
||||
* This is the heart shared by both servers, containing core functionalities such as authentication, API calls, request/response handling, and logging.
|
||||
|
||||
- **OpenAI API Compatibility**: Implements the `/v1/models` and `/v1/chat/completions` endpoints.
|
||||
- **Format Conversion**: Automatically converts requests/responses between OpenAI format and the internal Gemini format.
|
||||
- **Streaming Support**: Fully supports OpenAI's streaming responses (`"stream": true`).
|
||||
- **Flexible Authentication**: Supports API key validation through the `Authorization: Bearer <key>` request header, URL query parameters (`?key=...`), or the `x-goog-api-key` request header.
|
||||
- **Configurability**: The listening address, port, API key, and prompt logging mode can be configured via command-line arguments.
|
||||
- **Reuses Core Logic**: The underlying communication with Google services still uses `gemini-core.js`.
|
||||
---
|
||||
|
||||
## Installation
|
||||
## 💡 Core Advantages
|
||||
|
||||
1. **Environment Setup**:
|
||||
Create a `package.json` file in the project root directory with the content: `{"type": "module"}`. This is to avoid module type warnings.
|
||||
(This project already provides a `package.json` file, no need to create it manually)
|
||||
* ✅ **Break Through Official Limits**: Solves the problem of tight quotas on the official free Gemini API. With this project, you can use your Gemini CLI account authorization to enjoy higher daily request limits.
|
||||
* ✅ **Seamless OpenAI Compatibility**: Provides an interface fully compatible with the OpenAI API, allowing your existing toolchains and clients (like LobeChat, NextChat, etc.) to access Gemini at zero cost.
|
||||
* ✅ **Enhanced Controllability**: With powerful logging features, you can capture and record all request prompts, which is convenient for auditing, debugging, and building private datasets.
|
||||
* ✅ **Easy to Extend**: The code structure is clear, making it convenient for you to perform secondary development to implement custom features like unified prefix prompts, response caching, content filtering, etc.
|
||||
|
||||
### ⚠️ Current Limitations
|
||||
|
||||
* Some built-in command functions of the original Gemini CLI have not yet been implemented.
|
||||
* Multimodal capabilities (like image input) are still in the development plan (TODO).
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ Key Features
|
||||
|
||||
### 💎 Gemini API Server (`gemini-api-server.js`)
|
||||
|
||||
* 🔐 **Automatic Authentication & Token Renewal**: The first run will guide you through Google account authorization via a browser. The obtained OAuth token will be securely stored locally and automatically refreshed before expiration, ensuring uninterrupted service.
|
||||
* 🔗 **Simplified Manual Authorization Flow**:
|
||||
1. **Copy Authorization Link**: The terminal will output a Google authorization URL.
|
||||
2. **Browser Authorization**: Open the URL in a browser on any device with a GUI, log in, and grant permissions.
|
||||
3. **Paste Redirect URL**: After authorization, the browser will attempt to redirect to a `localhost` address. Paste it back into the terminal to complete authentication.
|
||||
> Credential file will be stored at:
|
||||
> * **Windows**: `C:\Users\USERNAME\.gemini\oauth_creds.json`
|
||||
> * **macOS/Linux**: `~/.gemini/oauth_creds.json`
|
||||
* 🔑 **Flexible API Key Validation**: Supports providing API keys via URL query parameters (`?key=...`) or the `x-goog-api-key` request header.
|
||||
* 🔧 **Role Normalization Fix**: Automatically adds the necessary 'user'/'model' roles to the request body and correctly handles `systemInstruction`.
|
||||
* 🤖 **Fixed Model List**: Defaults to providing and using the `gemini-2.5-pro` and `gemini-2.5-flash` models.
|
||||
* 🌐 **Full Gemini API Endpoint Support**: Fully implements `listModels`, `generateContent`, and `streamGenerateContent`.
|
||||
* 📜 **Fully Controllable Logging System**: Can output timestamped prompt logs to the console or a file, and display the remaining token validity period.
|
||||
|
||||
### 🔄 OpenAI Compatible API Server (`openai-api-server.js`)
|
||||
|
||||
* 🌍 **OpenAI API Compatibility**: Perfectly implements the core `/v1/models` and `/v1/chat/completions` endpoints.
|
||||
* 🔄 **Automatic Format Conversion**: Automatically and seamlessly converts requests/responses between OpenAI format and Gemini format internally.
|
||||
* 💨 **Streaming Support**: Fully supports OpenAI's streaming responses (`"stream": true`), providing a typewriter-like real-time experience.
|
||||
* 🛡️ **Multiple Authentication Methods**: Supports API key validation via `Authorization: Bearer <key>`, URL query parameters (`?key=...`), and the `x-goog-api-key` request header.
|
||||
* ⚙️ **Highly Configurable**: Flexibly configure listening address, port, API key, and log mode via command-line arguments.
|
||||
* ♻️ **Reuses Core Logic**: Shares `gemini-core.js` with the Gemini API Server at its core, ensuring stability and consistency.
|
||||
|
||||
---
|
||||
|
||||
## 📦 Installation Guide
|
||||
|
||||
1. **Prerequisites**:
|
||||
* Please ensure you have [Node.js](https://nodejs.org/) installed (recommended version >= 18.0.0).
|
||||
* This project already includes `package.json` and sets `{"type": "module"}`, so you don't need to create it manually.
|
||||
|
||||
2. **Install Dependencies**:
|
||||
After cloning this repository, execute the following in the project root directory:
|
||||
```bash
|
||||
npm install
|
||||
```
|
||||
This will install `google-auth-library` and `uuid`.
|
||||
This will automatically install necessary dependencies like `google-auth-library` and `uuid`.
|
||||
|
||||
## Usage Instructions and Command Line Examples
|
||||
---
|
||||
|
||||
## 🚀 Quick Start
|
||||
|
||||
### 1. Gemini API Server (`gemini-api-server.js`)
|
||||
|
||||
**Start the service** (the following parameters can be combined):
|
||||
|
||||
- **Default start**: Listen on `localhost:3000`, do not print prompts
|
||||
#### ▶️ Start the Service
|
||||
* **Default Start** (listens on `localhost:3000`)
|
||||
```bash
|
||||
node gemini-api-server.js
|
||||
```
|
||||
- **Specify listening IP**: Listen on all network interfaces (e.g., for Docker or LAN access)
|
||||
* **Listen on All Network Interfaces** (for Docker or LAN access)
|
||||
```bash
|
||||
node gemini-api-server.js 0.0.0.0
|
||||
```
|
||||
- **Print prompts to console**: Listen on `localhost` and output prompt details to the console
|
||||
* **Print Prompts to Console**
|
||||
```bash
|
||||
node gemini-api-server.js --log-prompts console
|
||||
```
|
||||
- **Print prompts to file**: Listen on `localhost` and save prompt details to a new file with a startup timestamp (e.g., `prompts-20231027-153055.log`)
|
||||
* **Combine Parameters** (specify IP, port, API Key, and log to a file)
|
||||
```bash
|
||||
node gemini-api-server.js --log-prompts file
|
||||
node gemini-api-server.js 0.0.0.0 --port 3001 --api-key your_secret_key --log-prompts file
|
||||
```
|
||||
- **Combine parameters** (parameter order does not matter):
|
||||
- Run on a specified IP and print prompts to the console
|
||||
```bash
|
||||
node gemini-api-server.js 192.168.1.100 --log-prompts console
|
||||
```
|
||||
- Run on all network interfaces and print prompts to a file
|
||||
```bash
|
||||
node gemini-api-server.js --log-prompts file 0.0.0.0
|
||||
```
|
||||
- Specify API Key and port
|
||||
```bash
|
||||
node gemini-api-server.js --api-key your_secret_key --port 3001
|
||||
```
|
||||
|
||||
**Call API Endpoints** (Default API Key: `123456`):
|
||||
|
||||
- **a) List available models** (GET request, key in URL parameter)
|
||||
#### 💻 Call the API (Default API Key: `123456`)
|
||||
* **List Models**
|
||||
```bash
|
||||
curl "http://localhost:3000/v1beta/models?key=123456"
|
||||
```
|
||||
- **b) Generate content - single turn conversation** (POST request, key in request header)
|
||||
* **Generate Content (with system prompt)**
|
||||
```bash
|
||||
curl "http://localhost:3000/v1beta/models/gemini-1.5-pro-latest:generateContent" \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "x-goog-api-key: 123456" \
|
||||
-d '{"contents":[{"parts":[{"text":"Explain what a proxy server is in one sentence"}]}]}'
|
||||
```
|
||||
- **c) Generate content - with system prompt** (POST request, key in request header, note `system_instruction`)
|
||||
```bash
|
||||
curl "http://localhost:3000/v1beta/models/gemini-1.5-pro-latest:generateContent" \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "x-goog-api-key: 123456" \
|
||||
-d '{
|
||||
-d '{
|
||||
"system_instruction": { "parts": [{ "text": "You are a cat named Neko." }] },
|
||||
"contents": [{ "parts": [{ "text": "Hello, what is your name?" }] }]
|
||||
}'
|
||||
}'
|
||||
```
|
||||
- **d) Stream generate content** (POST request, key in URL parameter)
|
||||
* **Stream Generate Content**
|
||||
```bash
|
||||
curl "http://localhost:3000/v1beta/models/gemini-1.5-flash-latest:streamGenerateContent?key=123456" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"contents":[{"parts":[{"text":"Write a five-line poem about the universe"}]}]}'
|
||||
-d '{"contents":[{"parts":[{"text":"Write a five-line poem about the universe"}]}]}'
|
||||
```
|
||||
|
||||
### 2. OpenAI Compatible API Server (`openai-api-server.js`)
|
||||
|
||||
**Start the service**:
|
||||
#### ▶️ Start the Service
|
||||
*Startup parameters are identical to `gemini-api-server.js`.*
|
||||
|
||||
- **Same as Gemini API Server**:
|
||||
* **Example** (listens on `localhost:8000`, API Key is `sk-your-key`)
|
||||
```bash
|
||||
node openai-api-server.js --port 8000 --api-key sk-your-key
|
||||
```
|
||||
|
||||
|
||||
**Call API Endpoints** (Assuming API Key: `your_secret_key`, service running on `localhost:8000`):
|
||||
|
||||
- **a) List available models**:
|
||||
#### 💻 Call the API (as an OpenAI client)
|
||||
* **List Models**
|
||||
```bash
|
||||
curl http://localhost:8000/v1/models \
|
||||
-H "Authorization: Bearer your_secret_key"
|
||||
-H "Authorization: Bearer sk-your-key"
|
||||
```
|
||||
- **b) Generate content - with system prompt (non-streaming)**:
|
||||
* **Generate Content (non-streaming)**
|
||||
```bash
|
||||
curl http://localhost:8000/v1/chat/completions \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "Authorization: Bearer your_secret_key" \
|
||||
-d '{
|
||||
-H "Authorization: Bearer sk-your-key" \
|
||||
-d '{
|
||||
"model": "gemini-1.5-pro-latest",
|
||||
"messages": [
|
||||
{"role": "system", "content": "You are a cat named Neko."},
|
||||
{"role": "user", "content": "Hello, what is your name?"}
|
||||
]
|
||||
}'
|
||||
}'
|
||||
```
|
||||
- **c) Generate content - streaming**:
|
||||
* **Stream Generate Content**
|
||||
```bash
|
||||
curl http://localhost:8000/v1/chat/completions \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "Authorization: Bearer your_secret_key" \
|
||||
-d '{
|
||||
-H "Authorization: Bearer sk-your-key" \
|
||||
-d '{
|
||||
"model": "gemini-1.5-flash-latest",
|
||||
"messages": [
|
||||
{"role": "user", "content": "Write a five-line poem about the universe"}
|
||||
],
|
||||
"stream": true
|
||||
}'
|
||||
}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🌟 Special Usage & Advanced Tips
|
||||
|
||||
* **🔌 Connect to Any OpenAI Client**: This is the killer feature of this project. Through `openai-api-server.js`, you can point the API address of any application that supports OpenAI (like LobeChat, NextChat, VS Code extensions, etc.) to this service to use Gemini seamlessly.
|
||||
|
||||
* **🔍 Centralized Request Monitoring & Auditing**: Use the `--log-prompts` parameter to capture all system prompts and user requests sent by clients. This is crucial for analyzing, debugging, and optimizing prompts, and even for building private datasets.
|
||||
|
||||
* **🛠️ Foundation for Secondary Development**:
|
||||
* **Unified System Prompt**: Modify `gemini-core.js` to enforce a unified, invisible system prompt for all requests, ensuring AI responses follow a specific role or format.
|
||||
* **Response Caching**: Add caching logic for frequently repeated questions to reduce API calls and improve response speed.
|
||||
* **Custom Content Filtering**: Add keyword filtering or content review logic before requests are sent or returned to meet compliance requirements.
|
||||
|
||||
* **⚖️ Multi-Account Load Balancing (Advanced Usage)**: Run multiple instances of `GeminiCli2API` (each authorized with a different Google account), and then use a load balancer like [gemini-balance](https://github.com/snailyp/gemini-balance/) to achieve load balancing. This can create a huge shared pool of free quota, ideal for teams or high-request scenarios.
|
||||
|
||||
---
|
||||
|
||||
## 📄 License
|
||||
|
||||
This project is licensed under the [**GNU General Public License v3 (GPLv3)**](https://www.gnu.org/licenses/gpl-3.0). For details, please see the `LICENSE` file in the root directory.
|
||||
|
||||
## 🙏 Acknowledgements
|
||||
|
||||
The development of this project was greatly inspired by the official Google Gemini CLI, and it references some of the code implementation from its `gemini-cli.ts` (Cline 3.18.0 version). Sincere thanks to the official Google team for their excellent work!
|
||||
|
|
|
|||
214
README.md
214
README.md
|
|
@ -1,117 +1,129 @@
|
|||
# GeminiCli2API
|
||||
<div align="center">
|
||||
该项目包含两个 Node.js HTTP 服务器。它们作为 Google Cloud Code Assist API 的本地代理。其中一个服务器还提供了与 OpenAI API 兼容的接口。可以抛弃终端界面，通过API的形式接入到任意客户端。
|
||||
|
||||
[中文](./README.md) / [English](./README-EN.md)
|
||||
# GeminiCli2API 🚀
|
||||
|
||||
**一个将 Google Gemini CLI 封装为本地 API 的强大代理，并提供 OpenAI 兼容接口。**
|
||||
|
||||
</div>
|
||||
|
||||
## 项目概述
|
||||
<div align="center">
|
||||
|
||||
- `gemini-api-server.js`: 这是一个独立的 Node.js HTTP 服务器。它作为 Google Cloud Code Assist API 的本地代理。该服务器提供所有功能和错误修复。它的设计稳健、灵活。通过全面可控的日志系统，可以方便地进行监控。
|
||||
- `openai-api-server.js`: 这个脚本基于 `gemini-api-server.js`。它创建了一个独立的 Node.js HTTP 服务器。此服务器也是 Google Cloud Code Assist API 的本地代理。但是，它对外提供了与 OpenAI API 兼容的接口。因此，任何支持 OpenAI API 的客户端可以直接使用它。
|
||||
- `gemini-core.js`: 这个文件包含两个服务器共享的核心逻辑。例如，认证、API 调用、请求/响应处理以及日志记录功能。
|
||||
[](https://www.gnu.org/licenses/gpl-3.0)
|
||||
[](https://nodejs.org/)
|
||||
|
||||
## 功能说明
|
||||
[**中文**](./README.md) | [**English**](./README-EN.md)
|
||||
|
||||
### 解决的问题
|
||||
</div>
|
||||
|
||||
- 解决了 Gemini 官方免费额度减少的问题。现在，用户可以使用 Gemini CLI 账号授权，每天进行 1000 次请求。
|
||||
- 提供了与 OpenAI API 的兼容性，方便现有 OpenAI 客户端使用。
|
||||
> `GeminiCli2API` 包含两个独立的 Node.js HTTP 服务器，它们作为 Google Cloud Code Assist API 的本地代理。其中一个服务器更是提供了与 OpenAI API 完全兼容的接口。这让您可以摆脱终端界面的束缚，将 Gemini 的强大能力以 API 的形式轻松接入到任何您喜爱的客户端或应用中。
|
||||
|
||||
### 目前的局限
|
||||
---
|
||||
|
||||
- 不能使用原版 Gemini CLI 的内置功能。
|
||||
- 不支持多模态能力。(todo)
|
||||
## 📝 项目概述
|
||||
|
||||
## 主要功能
|
||||
本项目由三个核心文件构成，各司其职：
|
||||
|
||||
### Gemini API Server (`gemini-api-server.js`)
|
||||
* `gemini-api-server.js`: 💎 **原生 Gemini 代理服务**
|
||||
* 一个独立的 Node.js HTTP 服务器，作为 Google Cloud Code Assist API 的本地代理。
|
||||
* 它提供了所有核心功能和错误修复，设计稳健、灵活，并配备了全面可控的日志系统，方便监控和调试。
|
||||
|
||||
- **自动认证与令牌续期**: 首次运行，脚本会引导用户通过浏览器完成 Google 账号手动授权。它将获取 OAuth 令牌。此令牌会安全地存储在本地，并在过期前自动刷新。这确保了服务的持续运行，无需手动干预。
|
||||
- **手动授权流程**:
|
||||
1. **复制授权链接**: 终端会输出一个 Google 授权 URL。请复制此 URL。
|
||||
2. **在浏览器中打开链接**: 在任何有图形界面的设备上 (例如你的本地电脑) 的浏览器中打开该 URL。
|
||||
3. **完成授权**: 登录你的 Google 账号并授予权限。
|
||||
4. **复制重定向后的 URL**: 授权后，浏览器会尝试重定向到一个URL，提取授权码，完成认证，并正常启动服务。
|
||||
- **灵活的 API 密钥校验**: 用户可以在 URL 查询参数 (`?key=...`) 或 `x-goog-api-key` 请求头中提供密钥。只要密钥正确，请求即可通过授权。密钥可以通过 `--api-key` 启动参数设置。
|
||||
- **角色规范化修复**: 服务器会自动为请求体添加必要的 'user'/'model' 角色。同时，它会正确保留 `systemInstruction` (或 `system_instruction`)。
|
||||
- **固定的模型列表**: 服务器专门提供并使用 `gemini-2.5-pro` 和 `gemini-2.5-flash` 模型。
|
||||
- **完整的 Gemini API 端点支持**: 实现了 `listModels`, `generateContent`, `streamGenerateContent`。
|
||||
- **全面可控的日志系统**: 包括令牌剩余有效期。它可以输出到控制台或文件的带时间戳的提示词日志。支持日志打印。
|
||||
* `openai-api-server.js`: 🔄 **OpenAI 兼容代理服务**
|
||||
* 基于 `gemini-api-server.js` 构建，同样作为 Google API 的代理。
|
||||
* 关键在于，它对外暴露了与 OpenAI API 兼容的接口。这意味着任何支持 OpenAI API 的客户端都无需修改代码，即可无缝切换使用。
|
||||
|
||||
### OpenAI 兼容 API Server (`openai-api-server.js`)
|
||||
* `gemini-core.js`: ⚙️ **核心共享逻辑**
|
||||
* 这是两个服务器共享的心脏，包含了认证、API 调用、请求/响应处理以及日志记录等核心功能。
|
||||
|
||||
- **OpenAI API 兼容性**: 实现了 `/v1/models` 和 `/v1/chat/completions` 端点。
|
||||
- **格式转换**: 自动将 OpenAI 格式的请求/响应与内部 Gemini 格式进行转换。
|
||||
- **流式传输支持**: 完全支持 OpenAI 的流式响应 (`"stream": true`)。
|
||||
- **灵活的认证**: 支持通过 `Authorization: Bearer <key>` 请求头、URL 查询参数 (`?key=...`) 或 `x-goog-api-key` 请求头进行 API 密钥校验。
|
||||
- **可配置性**: 可以通过命令行参数配置监听地址、端口、API 密钥和提示词日志模式。
|
||||
- **重用核心逻辑**: 底层仍使用 `gemini-core.js` 与 Google 服务通信。
|
||||
---
|
||||
|
||||
## 安装
|
||||
## 💡 核心优势
|
||||
|
||||
1. **环境设置**:
|
||||
在项目根目录创建一个 `package.json` 文件，内容为: `{"type": "module"}`。这是为了避免模块类型警告。
|
||||
(本项目已提供 `package.json` 文件，无需手动创建)
|
||||
* ✅ **突破官方限制**：解决了 Gemini 官方免费 API 额度紧张的问题。通过本项目，您可以使用 Gemini CLI 的账号授权，享受更高的每日请求限额。
|
||||
* ✅ **无缝兼容 OpenAI**：提供了与 OpenAI API 完全兼容的接口，让您现有的工具链和客户端（如 LobeChat, NextChat 等）可以零成本接入 Gemini。
|
||||
* ✅ **增强的可控性**：通过强大的日志功能，可以捕获并记录所有请求的提示词（Prompts），便于审计、调试和构建私有数据集。
|
||||
* ✅ **易于扩展**：代码结构清晰，方便您进行二次开发，实现如统一前置提示词、响应缓存、内容过滤等自定义功能。
|
||||
|
||||
### ⚠️ 目前的局限
|
||||
|
||||
* 暂未实现原版 Gemini CLI 的部分内置命令功能。
|
||||
* 多模态能力（如图片输入）尚在开发计划中 (TODO)。
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ 主要功能
|
||||
|
||||
### 💎 Gemini API Server (`gemini-api-server.js`)
|
||||
|
||||
* 🔐 **自动认证与令牌续期**: 首次运行将引导您通过浏览器完成 Google 账号授权。获取的 OAuth 令牌会安全存储在本地，并在过期前自动刷新，确保服务不间断。
|
||||
* 🔗 **简化的手动授权流程**:
|
||||
1. **复制授权链接**：终端会输出一个 Google 授权 URL。
|
||||
2. **浏览器授权**：在任何图形界面设备的浏览器中打开该 URL，登录并授予权限。
|
||||
3. **粘贴重定向URL**：授权后，浏览器会尝试重定向到一个 `localhost` 地址，回终端即可完成认证。
|
||||
> 凭证文件将存储于：
|
||||
> * **Windows**: `C:\Users\USERNAME\.gemini\oauth_creds.json`
|
||||
> * **macOS/Linux**: `~/.gemini/oauth_creds.json`
|
||||
* 🔑 **灵活的 API 密钥校验**: 支持通过 URL 查询参数 (`?key=...`) 或 `x-goog-api-key` 请求头提供 API 密钥。
|
||||
* 🔧 **角色规范化修复**: 自动为请求体添加必要的 'user'/'model' 角色，并正确处理 `systemInstruction`。
|
||||
* 🤖 **固定的模型列表**: 默认提供并使用 `gemini-1.5-pro-latest` 和 `gemini-1.5-flash-latest` 模型。
|
||||
* 🌐 **完整的 Gemini API 端点支持**: 完整实现了 `listModels`, `generateContent`, 和 `streamGenerateContent`。
|
||||
* 📜 **全面可控的日志系统**: 可将带时间戳的提示词日志输出到控制台或文件，并显示令牌剩余有效期。
|
||||
|
||||
### 🔄 OpenAI 兼容 API Server (`openai-api-server.js`)
|
||||
|
||||
* 🌍 **OpenAI API 兼容性**: 完美实现了 `/v1/models` 和 `/v1/chat/completions` 核心端点。
|
||||
* 🔄 **自动格式转换**: 在内部自动将 OpenAI 格式的请求/响应与 Gemini 格式进行无缝转换。
|
||||
* 💨 **流式传输支持**: 完全支持 OpenAI 的流式响应 (`"stream": true`)，提供打字机般的实时体验。
|
||||
* 🛡️ **多样的认证方式**: 支持 `Authorization: Bearer <key>`, URL 查询参数 (`?key=...`) 和 `x-goog-api-key` 请求头进行 API 密钥校验。
|
||||
* ⚙️ **高度可配置**: 可通过命令行参数灵活配置监听地址、端口、API 密钥和日志模式。
|
||||
* ♻️ **重用核心逻辑**: 底层与 Gemini API Server 共享 `gemini-core.js`，保证了稳定性与一致性。
|
||||
|
||||
---
|
||||
|
||||
## 📦 安装指南
|
||||
|
||||
1. **环境准备**:
|
||||
* 请确保您已安装 [Node.js](https://nodejs.org/) (建议版本 >= 18.0.0)。
|
||||
* 本项目已包含 `package.json` 并设置 `{"type": "module"}`，您无需手动创建。
|
||||
|
||||
2. **安装依赖**:
|
||||
克隆本仓库后，在项目根目录下执行：
|
||||
```bash
|
||||
npm install
|
||||
```
|
||||
这将安装 `google-auth-library` 和 `uuid`。
|
||||
这将自动安装 `google-auth-library` 和 `uuid` 等必要依赖。
|
||||
|
||||
## 使用说明 与 命令行示例
|
||||
---
|
||||
|
||||
## 🚀 快速开始
|
||||
|
||||
### 1. Gemini API Server (`gemini-api-server.js`)
|
||||
|
||||
**启动服务** (可以组合使用以下参数):
|
||||
|
||||
- **默认启动**: 监听 `localhost:3000`，不打印提示词
|
||||
#### ▶️ 启动服务
|
||||
* **默认启动** (监听 `localhost:3000`)
|
||||
```bash
|
||||
node gemini-api-server.js
|
||||
```
|
||||
- **指定监听 IP**: 监听所有网络接口 (例如，用于 Docker 或局域网访问)
|
||||
* **监听所有网络接口** (用于 Docker 或局域网访问)
|
||||
```bash
|
||||
node gemini-api-server.js 0.0.0.0
|
||||
```
|
||||
- **打印提示词到控制台**: 监听 `localhost`，并在控制台输出提示词详情
|
||||
* **打印提示词到控制台**
|
||||
```bash
|
||||
node gemini-api-server.js --log-prompts console
|
||||
```
|
||||
- **打印提示词到文件**: 监听 `localhost`，并将提示词详情保存到一个带启动时间戳的新文件中 (例如: `prompts-20231027-153055.log`)
|
||||
* **组合参数** (指定 IP、端口、API Key 并记录日志到文件)
|
||||
```bash
|
||||
node gemini-api-server.js --log-prompts file
|
||||
node gemini-api-server.js 0.0.0.0 --port 3001 --api-key your_secret_key --log-prompts file
|
||||
```
|
||||
- **组合使用参数** (参数顺序无关):
|
||||
- 在指定 IP 上运行，并打印提示词到控制台
|
||||
```bash
|
||||
node gemini-api-server.js 192.168.1.100 --log-prompts console
|
||||
```
|
||||
- 在所有网络接口上运行，并打印提示词到文件
|
||||
```bash
|
||||
node gemini-api-server.js --log-prompts file 0.0.0.0
|
||||
```
|
||||
- 指定 API Key 和端口
|
||||
```bash
|
||||
node gemini-api-server.js --api-key your_secret_key --port 3001
|
||||
```
|
||||
|
||||
**调用 API 接口** (默认 API Key: `123456`):
|
||||
|
||||
- **a) 列出可用模型** (GET 请求，密钥在 URL 参数中)
|
||||
#### 💻 调用 API (默认 API Key: `123456`)
|
||||
* **列出模型**
|
||||
```bash
|
||||
curl "http://localhost:3000/v1beta/models?key=123456"
|
||||
```
|
||||
- **b) 生成内容 - 单轮对话** (POST 请求，密钥在请求头中)
|
||||
* **生成内容 (带系统提示)**
|
||||
```bash
|
||||
curl "http://localhost:3000/v1beta/models/gemini-2.5-pro:generateContent" \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "x-goog-api-key: 123456" \
|
||||
-d '{"contents":[{"parts":[{"text":"用一句话解释什么是代理服务器"}]}]}'
|
||||
```
|
||||
- **c) 生成内容 - 带系统提示词** (POST 请求，密钥在请求头中，注意 `system_instruction`)
|
||||
```bash
|
||||
curl "http://localhost:3000/v1beta/models/gemini-2.5-pro:generateContent" \
|
||||
curl "http://localhost:3000/v1beta/models/gemini-1.5-pro-latest:generateContent" \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "x-goog-api-key: 123456" \
|
||||
-d '{
|
||||
|
|
@ -119,49 +131,77 @@
|
|||
"contents": [{ "parts": [{ "text": "你好，你叫什么名字？" }] }]
|
||||
}'
|
||||
```
|
||||
- **d) 流式生成内容** (POST 请求，密钥在 URL 参数中)
|
||||
* **流式生成内容**
|
||||
```bash
|
||||
curl "http://localhost:3000/v1beta/models/gemini-2.5-flash:streamGenerateContent?key=123456" \
|
||||
curl "http://localhost:3000/v1beta/models/gemini-1.5-flash-latest:streamGenerateContent?key=123456" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"contents":[{"parts":[{"text":"写一首关于宇宙的五行短诗"}]}]}'
|
||||
```
|
||||
|
||||
### 2. OpenAI 兼容 API Server (`openai-api-server.js`)
|
||||
|
||||
**启动服务** :
|
||||
#### ▶️ 启动服务
|
||||
*启动参数与 `gemini-api-server.js` 完全一致。*
|
||||
|
||||
- **同Gemini API Server 保持一致**:
|
||||
* **示例** (监听 `localhost:8000`, API Key 为 `sk-your-key`)
|
||||
```bash
|
||||
node openai-api-server.js --port 8000 --api-key sk-your-key
|
||||
```
|
||||
|
||||
|
||||
**调用 API 接口** (假设 API Key: `your_secret_key`, 服务运行在 `localhost:8000`):
|
||||
|
||||
- **a) 列出可用模型**:
|
||||
#### 💻 调用 API (以 OpenAI 客户端方式)
|
||||
* **列出模型**
|
||||
```bash
|
||||
curl http://localhost:8000/v1/models \
|
||||
-H "Authorization: Bearer your_secret_key"
|
||||
-H "Authorization: Bearer sk-your-key"
|
||||
```
|
||||
- **b) 生成内容 - 带系统提示词 (非流式)**:
|
||||
* **生成内容 (非流式)**
|
||||
```bash
|
||||
curl http://localhost:8000/v1/chat/completions \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "Authorization: Bearer your_secret_key" \
|
||||
-H "Authorization: Bearer sk-your-key" \
|
||||
-d '{
|
||||
"model": "gemini-2.5-pro",
|
||||
"model": "gemini-1.5-pro-latest",
|
||||
"messages": [
|
||||
{"role": "system", "content": "你是一只名叫 Neko 的猫。"},
|
||||
{"role": "user", "content": "你好，你叫什么名字？"}
|
||||
]
|
||||
}'
|
||||
```
|
||||
- **c) 生成内容 - 流式**:
|
||||
* **流式生成内容**
|
||||
```bash
|
||||
curl http://localhost:8000/v1/chat/completions \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "Authorization: Bearer your_secret_key" \
|
||||
-H "Authorization: Bearer sk-your-key" \
|
||||
-d '{
|
||||
"model": "gemini-2.5-flash",
|
||||
"model": "gemini-1.5-flash-latest",
|
||||
"messages": [
|
||||
{"role": "user", "content": "写一首关于宇宙的五行短诗"}
|
||||
],
|
||||
"stream": true
|
||||
}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🌟 特殊用法与进阶技巧
|
||||
|
||||
* **🔌 对接任意 OpenAI 客户端**: 这是本项目的杀手级功能。通过 `openai-api-server.js`，将任何支持 OpenAI 的应用（如 LobeChat, NextChat, VS Code 插件等）的 API 地址指向本服务，即可无缝使用 Gemini。
|
||||
|
||||
* **🔍 中心化请求监控与审计**: 使用 `--log-prompts` 参数捕获所有客户端发送的系统提示词和用户请求。这对于分析、调试和优化提示词，甚至构建私有数据集都至关重要。
|
||||
|
||||
* **🛠️ 作为二次开发基石**:
|
||||
* **统一系统提示**: 修改 `gemini-core.js`，为所有请求强制添加一个统一的、不可见的系统提示词，确保 AI 回复遵循特定角色或格式。
|
||||
* **响应缓存**: 对高频重复问题添加缓存逻辑，降低 API 调用，提升响应速度。
|
||||
* **自定义内容过滤**: 在请求发送或返回前增加关键词过滤或内容审查逻辑，满足合规要求。
|
||||
|
||||
* **⚖️ 多账号负载均衡 (高级用法)**: 运行多个 `GeminiCli2API` 实例（每个使用不同 Google 账号授权），再通过[gemini-balance](https://github.com/snailyp/gemini-balance/) 等实现负载均衡。这能创建一个巨大的共享免费额度池，非常适合团队或高请求量场景。
|
||||
|
||||
---
|
||||
|
||||
## 📄 开源许可
|
||||
|
||||
本项目遵循 [**GNU General Public License v3 (GPLv3)**](https://www.gnu.org/licenses/gpl-3.0) 开源许可。详情请查看根目录下的 `LICENSE` 文件。
|
||||
|
||||
## 🙏 致谢
|
||||
|
||||
本项目的开发受到了官方 Google Gemini CLI 的极大启发，并参考了其 `gemini-cli.ts` (Cline 3.18.0 版本) 的部分代码实现。在此对 Google 官方团队的卓越工作表示衷心的感谢！
|
||||
Loading…
Reference in a new issue