articles/fastapi-gemini-proxy-tutorial.md

# 使用 FastAPI 搭建 Gemini API 转发代理教程

## 1. 项目简介

本项目旨在搭建一个基于 FastAPI 的通用 API 转发代理，主要用于转发对 Google Gemini API（特别是其 OpenAI 兼容 API）的请求。通过此代理，您可以解决直接访问 Gemini API 可能遇到的地域限制、集中管理 API 密钥以及处理客户端请求头兼容性等问题。

## 2. 核心功能

*   **代理认证**：代理自身支持 API 密钥认证，确保只有授权客户端才能使用代理服务。
*   **请求转发**：接收来自客户端的 HTTP 请求（GET, POST, PUT, DELETE），并将其转发到预配置的目标 API。
*   **请求/响应处理**：处理请求头、查询参数和请求体，并将目标 API 的响应原封不动地返回给客户端。
*   **环境变量配置**：支持通过 `.env` 文件配置代理自身的认证密钥 (`PROXY_API_KEY`)、目标 API 的基 URL (`GEMINI_BASE_URL`) 和认证信息 (`GEMINI_API_KEY`)。
*   **健康检查**：提供一个简单的 `/health` 端点，用于验证代理服务是否正常运行。
*   **User-Agent 修改**：强制将转发请求的 `User-Agent` 头设置为 `curl/8.7.1`，以解决某些客户端（如 Postman）可能遇到的兼容性问题。

## 3. 技术栈

*   **Python 3.9+**
*   **FastAPI**：高性能 Python Web 框架。
*   **Uvicorn**：ASGI 服务器。
*   **httpx**：异步 HTTP 客户端。
*   **python-dotenv**：环境变量管理。

## 4. 环境搭建与部署

### 4.1. 创建虚拟环境并安装依赖

建议使用 `conda` 或 `venv` 创建独立的 Python 虚拟环境：

```bash
conda create -n airs python=3.9
conda activate airs
```

在项目根目录创建 `requirements.txt` 文件，并添加以下内容：

```
fastapi
uvicorn[standard]
httpx
python-dotenv
```

然后安装依赖：

```bash
pip install -r requirements.txt
```

### 4.2. 配置环境变量

在项目根目录创建 `.env` 文件，并配置代理自身的 API 密钥、Gemini API 密钥和 OpenAI 兼容 API 的 Base URL：

```dotenv
PROXY_API_KEY="YOUR_PROXY_API_KEY"
GEMINI_API_KEY="YOUR_GEMINI_API_KEY"
GEMINI_BASE_URL="https://generativelanguage.googleapis.com/v1beta/openai"
```

请将 `YOUR_PROXY_API_KEY` 替换为您为代理设置的密钥，将 `YOUR_GEMINI_API_KEY` 替换为您的实际 Gemini API 密钥。

### 4.3. `app.py` 代码实现

创建 `app.py` 文件，并添加以下代码：

```python
# uvicorn app:app --host 0.0.0.0 --port 7860 --reload 

from fastapi import FastAPI, Request, HTTPException, Depends, status
from fastapi.responses import Response
from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials
import httpx
import os
from dotenv import load_dotenv

# 加载环境变量
load_dotenv()

# 从环境变量获取代理自身的API密钥
PROXY_API_KEY = os.getenv("PROXY_API_KEY")

# 定义HTTPBearer安全方案
security = HTTPBearer()

# 依赖函数：验证代理的API密钥
def verify_proxy_api_key(credentials: HTTPAuthorizationCredentials = Depends(security)):
    if not PROXY_API_KEY or credentials.credentials != PROXY_API_KEY:
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="Invalid or missing proxy API key",
            headers={"WWW-Authenticate": "Bearer"},
        )
    return credentials.credentials

app = FastAPI(title="Gemini Proxy API")

@app.get("/")
def greet_json():
    return {"Hello": "World!"}

# 3. 健康检查接口（可选，用于验证服务是否正常）
@app.get("/health")
async def health_check():
    return {"status": "ok", "message": "Proxy service is running."}

# 1. 配置Gemini真实信息
GEMINI_API_KEY = os.getenv("GEMINI_API_KEY")
GEMINI_BASE_URL = os.getenv("GEMINI_BASE_URL")
print(f"Using Gemini Base URL: {GEMINI_BASE_URL}")
print(f"Using Gemini API Key: {GEMINI_API_KEY}")

# 2. 通用转发接口（匹配Gemini的/predict等端点，路径动态匹配）
@app.api_route("/{path:path}", methods=["GET", "POST", "PUT", "DELETE"])
async def proxy_gemini(request: Request, path: str, proxy_api_key: str = Depends(verify_proxy_api_key)): # 添加代理认证依赖
    # 拼接Gemini真实请求URL
    gemini_url = f"{GEMINI_BASE_URL}/{path}"
    
    # 提取客户端请求的headers和body，透传给Gemini
    client_headers = dict(request.headers)
    # 移除FastAPI自带的Host头，避免Gemini校验报错
    client_headers.pop("host", None)
    
    # 将User-Agent改为curl/8.7.1，以模拟curl请求
    client_headers["User-Agent"] = "curl/8.7.1"
    
    # 添加Authorization头，用于Gemini的OpenAI兼容API
    if GEMINI_API_KEY:
        client_headers["Authorization"] = f"Bearer {GEMINI_API_KEY}"
    
    try:
        # 读取客户端请求体
        client_body = await request.body()
        
        # 使用httpx异步客户端发起请求
        async with httpx.AsyncClient() as client:
            response = await client.request(
                method=request.method,
                url=gemini_url,
                headers=client_headers,
                content=client_body,
                timeout=30
            )
        
        # 将Gemini的响应透传给客户端
        return Response(
            content=response.content,
            status_code=response.status_code,
            headers=dict(response.headers)
        )
    
    except httpx.RequestError as e:
        raise HTTPException(status_code=500, detail=f"转发请求失败：{str(e)}")
    except httpx.HTTPStatusError as e:
        raise HTTPException(status_code=e.response.status_code, detail=f"目标API返回错误：{e.response.text}")
    except Exception as e:
        raise HTTPException(status_code=500, detail=f"转发失败：{str(e)}")
```

### 4.4. 运行应用程序

在项目根目录，激活您的虚拟环境并运行 FastAPI 应用：

```bash
conda activate airs
uvicorn app:app --host 0.0.0.0 --port 7860 --reload
```

应用程序将在 `http://0.0.0.0:7860` 上运行。

## 5. 如何使用代理

### 5.1. 健康检查

您可以通过访问 `/health` 端点来检查代理服务是否正常运行：

```bash
curl -X GET http://0.0.0.0:7860/health
```

预期响应：

```json
{"status":"ok","message":"Proxy service is running."}
```

### 5.2. 调用 Gemini OpenAI 兼容 API

要通过代理调用 Gemini 模型（例如 `gemini-2.5-flash-preview-05-20`），您需要向代理的 `/v1/chat/completions` 端点发送一个 POST 请求，并在请求体中指定模型名称和消息。**同时，您需要在请求头中包含代理自身的 API 密钥。**

以下是一个 `curl` 命令示例（请将 `YOUR_PROXY_API_KEY` 替换为您的实际代理密钥）：

```bash
curl -X POST http://0.0.0.0:7860/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_PROXY_API_KEY" \
-d '{
  "model": "gemini-2.5-flash-preview-05-20",
  "messages": [
    {
      "role": "user",
      "content": "你好，请介绍一下你自己。"
    }
  ],
  "temperature": 0.7
}'
```

如果您将代理部署到 Hugging Face Spaces，例如部署在 `https://airsltd-superproxy.hf.space`，则 `curl` 命令应如下所示：

```bash
curl -X POST https://airsltd-superproxy.hf.space/v1/chat/completions \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_PROXY_API_KEY' \
--data '{
  "model": "gemini-2.5-flash-preview-05-20",
  "messages": [
    {
      "role": "user",
      "content": "你好，请介绍一下你自己。"
    }
  ],
  "temperature": 0.7
}'
```

## 6. 常见问题与解决方案

*   **代理认证失败 (401 Unauthorized)**：
    *   **问题**：当您尝试调用代理时，收到 `401 Unauthorized` 错误，并提示“Invalid or missing proxy API key”。
    *   **原因**：这表示您没有在请求头中提供正确的 `Authorization: Bearer YOUR_PROXY_API_KEY`，或者 `PROXY_API_KEY` 环境变量未在代理部署环境中正确设置。
    *   **解决方案**：确保您的客户端请求包含正确的 `Authorization: Bearer YOUR_PROXY_API_KEY` 头，并且 `YOUR_PROXY_API_KEY` 与 `.env` 文件中配置的值一致。如果部署在 Hugging Face Spaces，请确保 Space 的环境变量中已设置 `PROXY_API_KEY`。

*   **“User location is not supported for the API use.”**：此错误来自 Gemini API，表明您的请求源 IP 地址所在的区域不受 Gemini API 支持。这通常发生在本地测试时。部署代理到支持的区域（例如 Hugging Face Spaces）可以解决此问题。

*   **Postman “Error: incorrect header check”**：此错误通常是由于 Postman 自动添加的某些请求头与部署环境或代理不兼容。本项目已通过强制设置 `User-Agent: curl/8.7.1` 来尝试解决此问题。如果问题仍然存在，请检查 Postman 发送的其他请求头，并尝试禁用非必要的头部。