# 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. 上传文件
```bash
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. 列出文件
```bash
curl "http://your-api.com/v1beta/files?key=YOUR_API_KEY"
```

**响应示例**：
```json
{
  "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**
   ```bash
   -H "Authorization: Bearer YOUR_API_KEY"
   ```

2. **x-goog-api-key Header**
   ```bash
   -H "x-goog-api-key: YOUR_API_KEY"
   ```

3. **Query Parameter**
   ```bash
   ?key=YOUR_API_KEY
   ```

## 特性

### ✅ 完全隔离
- 独立的路由设置
- 独立的认证逻辑
- 独立的中间件链
- 不影响其他 API 功能

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

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

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

## 配置

### 环境变量配置（可选）

如果需要支持大文件上传（超过默认限制），可以在 `docker-compose.yml` 或环境变量中配置：

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

或在启动时设置环境变量：
```bash
export MAX_REQUEST_BODY_MB=500
```

## 注意事项

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)
  - 初始版本
  - 完全独立的模块架构
  - 支持文件上传、列表、获取、删除操作
  - 多种认证方式支持
  - 自动渠道选择