new-api/docs/GEMINI_FILE_API.md

Gemini File API 独立模块

概述

Gemini File API 是一个完全独立的模块，与其他 API 逻辑完全隔离，不会相互干扰。

支持的功能：

• ✅ 文件上传 (POST /upload/v1beta/files)
• ✅ 文件列表 (GET /v1beta/files)

注意：本模块仅实现了文件上传和列表功能，这是使用 Gemini File API 的核心功能。如需获取单个文件信息或删除文件，可以通过列表接口获取所有文件信息。

架构设计

1. 独立的路由模块

• 文件: router/gemini_file_router.go
• 功能: 专门处理 Gemini 文件操作的路由
• 路径:
  • GET /v1beta/files - 列出文件
  • POST /upload/v1beta/files - 上传文件

2. 独立的认证中间件

• 文件: middleware/gemini_file_auth.go
• 功能:
  • 专门为 Gemini File API 设计的认证逻辑
  • 支持多种认证方式（Authorization header, x-goog-api-key, query parameter）
  • 自动查找可用的 Gemini 渠道
  • 不依赖其他中间件

3. 独立的控制器

• 文件: controller/relay_gemini_file.go
• 功能: 处理所有文件操作的业务逻辑
• 方法:
  • RelayGeminiFileList - 列出文件
  • RelayGeminiFileUpload - 上传文件

4. 独立的辅助函数

• 文件: relay/channel/gemini/file_helper.go
• 功能:
  • URL 构建
  • 请求转发
  • Multipart 表单处理

使用方式

1. 上传文件

curl -X POST "http://your-api.com/upload/v1beta/files?key=YOUR_API_KEY" \
  -F "file=@/path/to/file.pdf" \
  -F "display_name=My Document"

2. 列出文件

curl "http://your-api.com/v1beta/files?key=YOUR_API_KEY"

响应示例：

{
  "files": [
    {
      "name": "files/abc-123",
      "displayName": "My Document",
      "mimeType": "application/pdf",
      "sizeBytes": "12345",
      "createTime": "2024-01-20T10:00:00Z",
      "updateTime": "2024-01-20T10:00:00Z",
      "uri": "https://generativelanguage.googleapis.com/v1beta/files/abc-123"
    }
  ]
}

认证方式

支持以下任意一种认证方式：

1. Authorization Header

   -H "Authorization: Bearer YOUR_API_KEY"
   

   1. x-goog-api-key Header bash -H "x-goog-api-key: YOUR_API_KEY"

2. Query Parameter

   ?key=YOUR_API_KEY
   

   特性

   ✅ 完全隔离

   • 独立的路由设置
   • 独立的认证逻辑
   • 独立的中间件链
   • 不影响其他 API 功能

   ✅ 自动渠道选择

   • 自动查找可用的 Gemini 渠道
   • 支持多个 Gemini 模型作为备选
   • 失败自动重试其他渠道

   ✅ 多种认证方式

   • 灵活的认证方式支持
   • 兼容 OpenAI、Gemini、Claude 等多种 API 风格

   ✅ 大文件支持

   • 支持最大 500MB 的文件上传
   • 流式传输，内存占用低

   配置

   在 docker-compose.yml 中配置：

   environment:
   - MAX_REQUEST_BODY_MB=500  # 支持最大 500MB 文件
   

注意事项

1. 文件过期: 上传的文件会在 48 小时后自动过期
2. API Key 权限: 确保使用的 API Key 有访问 Gemini File API 的权限
3. 渠道配置: 需要在系统中配置至少一个 Gemini 渠道
4. 支持的模型:
   • gemini-2.0-flash
   • gemini-1.5-flash
   • gemini-1.5-pro
   • gemini-2.0-flash-exp
   • gemini-pro
   • gemini-1.0-pro

故障排除

问题: "No available Gemini channel"

解决方案:

1. 检查是否配置了 Gemini 渠道
2. 确认渠道状态为启用
3. 验证渠道支持的模型列表

问题: "API key is required"

解决方案:

1. 确保请求中包含 API Key
2. 检查 API Key 格式是否正确
3. 验证 API Key 是否有效

问题: 文件上传失败

解决方案:

1. 检查文件大小是否超过限制
2. 确认 MAX_REQUEST_BODY_MB 配置
3. 验证 Gemini API Key 权限

开发指南

添加新的文件操作

1. 在 controller/relay_gemini_file.go 中添加新的处理函数
2. 在 router/gemini_file_router.go 中注册新的路由
3. 如需特殊逻辑，在 relay/channel/gemini/file_helper.go 中添加辅助函数

修改认证逻辑

编辑 middleware/gemini_file_auth.go 中的 GeminiFileAuth 函数。

自定义渠道选择

修改 middleware/gemini_file_auth.go 中的 findGeminiFileChannel 函数。

版本历史

• v1.0.0 (2026-01-20)
  • 初始版本
  • 完全独立的模块架构
  • 支持文件上传、列表、获取、删除操作
  • 多种认证方式支持
  • 自动渠道选择