feat: Add Files API support with upload, list, get and delete operations

- Implement complete Files API compatible with Gemini API format
- Support resumable file uploads with chunked transfer (tested with 15MB video)
- Create file management service with database tracking
- Add file domain models and API request/response objects
- Implement file routes with proper authentication
- Use fixed API key for Files API requests (due to Google API restrictions)
- Support file state management (PROCESSING, ACTIVE, FAILED)
- Add scheduled task for automatic expired file cleanup
- Integrate seamlessly with existing key management and load balancing
This commit is contained in:
cxyfer
2025-07-12 03:33:39 +08:00
parent b3da021803
commit 5eb2dfd822
16 changed files with 1549 additions and 7 deletions
+1
View File
@@ -0,0 +1 @@
# Intentionally empty __init__.py file
+248
View File
@@ -0,0 +1,248 @@
"""
文件上传处理器
处理 Google 的可恢复上传协议
"""
import hashlib
from typing import Dict, Any, Optional
from datetime import datetime, timezone, timedelta
from httpx import AsyncClient
from fastapi import Request, Response, HTTPException
from fastapi.responses import StreamingResponse
from app.database import services as db_services
from app.database.models import FileState
from app.log.logger import get_files_logger
logger = get_files_logger()
class FileUploadHandler:
"""处理文件分块上传"""
def __init__(self):
self.chunk_size = 8 * 1024 * 1024 # 8MB
async def handle_upload_chunk(
self,
upload_url: str,
request: Request,
files_service=None # 添加 files_service 參數
) -> Response:
"""
处理上传分块
Args:
upload_url: 上传 URL
request: FastAPI 请求对象
files_service: 文件服務實例
Returns:
Response: 响应对象
"""
try:
# 获取请求头
headers = {}
# 复制必要的上传头
upload_headers = [
"x-goog-upload-command",
"x-goog-upload-offset",
"content-type",
"content-length"
]
for header in upload_headers:
if header in request.headers:
# 转换为正确的格式
key = "-".join(word.capitalize() for word in header.split("-"))
headers[key] = request.headers[header]
# 读取请求体
body = await request.body()
# 检查是否是最后一块
is_final = "finalize" in headers.get("X-Goog-Upload-Command", "")
logger.debug(f"Upload command: {headers.get('X-Goog-Upload-Command', '')}, is_final: {is_final}")
# 转发到真实的上传 URL
async with AsyncClient() as client:
response = await client.post(
upload_url,
headers=headers,
content=body,
timeout=300.0 # 5分钟超时
)
if response.status_code not in [200, 201, 308]:
logger.error(f"Upload chunk failed: {response.status_code} - {response.text}")
raise HTTPException(status_code=response.status_code, detail="Upload failed")
# 如果是最后一块,更新文件状态
if is_final and response.status_code in [200, 201]:
logger.debug(f"Upload finalized with status {response.status_code}")
try:
# 解析響應獲取文件信息
response_data = response.json()
logger.debug(f"Upload complete response data: {response_data}")
file_data = response_data.get("file", {})
# 獲取真實的文件名
real_file_name = file_data.get("name")
logger.debug(f"Upload response: {response_data}")
if real_file_name and files_service:
logger.info(f"Upload completed, file name: {real_file_name}")
# 從會話中獲取信息
session_info = await files_service.get_upload_session(upload_url)
logger.debug(f"Retrieved session info for {upload_url}: {session_info}")
if session_info:
# 創建文件記錄
now = datetime.now(timezone.utc)
expiration_time = now + timedelta(hours=48)
# 處理過期時間格式(Google 可能返回納秒級精度)
expiration_time_str = file_data.get("expirationTime", expiration_time.isoformat() + "Z")
# 處理納秒格式:2025-07-11T02:02:52.531916141Z -> 2025-07-11T02:02:52.531916Z
if expiration_time_str.endswith("Z"):
# 移除 Z
expiration_time_str = expiration_time_str[:-1]
# 如果有納秒(超過6位小數),截斷到微秒
if "." in expiration_time_str:
date_part, frac_part = expiration_time_str.rsplit(".", 1)
if len(frac_part) > 6:
frac_part = frac_part[:6]
expiration_time_str = f"{date_part}.{frac_part}"
# 添加時區
expiration_time_str += "+00:00"
# 獲取文件狀態(Google 可能返回 PROCESSING
file_state = file_data.get("state", "PROCESSING")
logger.debug(f"File state from Google: {file_state}")
# 將字符串狀態轉換為枚舉
if file_state == "ACTIVE":
state_enum = FileState.ACTIVE
elif file_state == "PROCESSING":
state_enum = FileState.PROCESSING
elif file_state == "FAILED":
state_enum = FileState.FAILED
else:
logger.warning(f"Unknown file state: {file_state}, defaulting to PROCESSING")
state_enum = FileState.PROCESSING
await db_services.create_file_record(
name=real_file_name,
mime_type=file_data.get("mimeType", session_info["mime_type"]),
size_bytes=int(file_data.get("sizeBytes", session_info["size_bytes"])),
api_key=session_info["api_key"],
uri=file_data.get("uri", f"https://generativelanguage.googleapis.com/v1beta/{real_file_name}"),
create_time=now,
update_time=now,
expiration_time=datetime.fromisoformat(expiration_time_str),
state=state_enum,
display_name=file_data.get("displayName", session_info.get("display_name", "")),
sha256_hash=file_data.get("sha256Hash"),
user_token=session_info["user_token"]
)
logger.info(f"Created file record: name={real_file_name}, api_key={session_info['api_key'][:8]}...{session_info['api_key'][-4:]}")
else:
logger.warning(f"No upload session found for URL: {upload_url}")
else:
logger.warning(f"Missing real_file_name or files_service: real_file_name={real_file_name}, files_service={files_service}")
# 返回完整的文件信息
return Response(
content=response.content,
status_code=response.status_code,
headers=dict(response.headers)
)
except Exception as e:
logger.error(f"Failed to create file record: {str(e)}", exc_info=True)
else:
logger.debug(f"Upload chunk processed: is_final={is_final}, status={response.status_code}")
# 返回响应
response_headers = dict(response.headers)
# 确保包含必要的头
if response.status_code == 308: # Resume Incomplete
if "x-goog-upload-status" not in response_headers:
response_headers["x-goog-upload-status"] = "active"
return Response(
content=response.content,
status_code=response.status_code,
headers=response_headers
)
except HTTPException:
raise
except Exception as e:
logger.error(f"Failed to handle upload chunk: {str(e)}")
raise HTTPException(status_code=500, detail=f"Internal error: {str(e)}")
async def proxy_upload_request(
self,
request: Request,
upload_url: str,
files_service=None
) -> Response:
"""
代理上传请求
Args:
request: FastAPI 请求对象
upload_url: 目标上传 URL
files_service: 文件服務實例
Returns:
Response: 代理响应
"""
logger.debug(f"Proxy upload request: {request.method}, {upload_url}")
try:
# 如果是 GET 请求,返回上传状态
if request.method == "GET":
return await self._get_upload_status(upload_url)
# 处理 POST/PUT 请求
return await self.handle_upload_chunk(upload_url, request, files_service)
except Exception as e:
logger.error(f"Failed to proxy upload request: {str(e)}")
raise HTTPException(status_code=500, detail=f"Internal error: {str(e)}")
async def _get_upload_status(self, upload_url: str) -> Response:
"""
获取上传状态
Args:
upload_url: 上传 URL
Returns:
Response: 状态响应
"""
try:
async with AsyncClient() as client:
response = await client.get(upload_url)
return Response(
content=response.content,
status_code=response.status_code,
headers=dict(response.headers)
)
except Exception as e:
logger.error(f"Failed to get upload status: {str(e)}")
raise HTTPException(status_code=500, detail=f"Internal error: {str(e)}")
# 单例实例
_upload_handler_instance: Optional[FileUploadHandler] = None
def get_upload_handler() -> FileUploadHandler:
"""获取上传处理器单例实例"""
global _upload_handler_instance
if _upload_handler_instance is None:
_upload_handler_instance = FileUploadHandler()
return _upload_handler_instance
+501
View File
@@ -0,0 +1,501 @@
"""
文件管理服务
"""
import json
import hashlib
import uuid
from datetime import datetime, timedelta, timezone
from typing import Optional, Dict, Any, Tuple, List
from httpx import AsyncClient, Headers
from collections import defaultdict
import asyncio
from app.config.config import settings
from app.database import services as db_services
from app.database.models import FileRecord, FileState
from app.domain.file_models import FileMetadata, ListFilesResponse
from fastapi import HTTPException
from app.log.logger import get_files_logger
from app.service.client.api_client import GeminiApiClient
from app.service.key.key_manager import get_key_manager_instance
logger = get_files_logger()
# 全局上傳會話存儲
_upload_sessions: Dict[str, Dict[str, Any]] = {}
_upload_sessions_lock = asyncio.Lock()
class FilesService:
"""文件管理服务类"""
def __init__(self):
self.api_client = GeminiApiClient(base_url=settings.BASE_URL)
self.key_manager = None
async def _get_key_manager(self):
"""获取 KeyManager 实例"""
if not self.key_manager:
self.key_manager = await get_key_manager_instance(
settings.API_KEYS,
settings.VERTEX_API_KEYS
)
return self.key_manager
async def initialize_upload(
self,
headers: Dict[str, str],
body: Optional[bytes],
user_token: str,
request_host: str = None # 添加請求主機參數
) -> Tuple[Dict[str, Any], Dict[str, str]]:
"""
初始化文件上传
Args:
headers: 请求头
body: 请求体
user_token: 用户令牌
Returns:
Tuple[Dict[str, Any], Dict[str, str]]: (响应体, 响应头)
"""
try:
# 获取可用的 API key
key_manager = await self._get_key_manager()
api_key = await key_manager.get_next_key()
if not api_key:
raise HTTPException(status_code=503, detail="No available API keys")
# 转发请求到真实的 Gemini API
async with AsyncClient() as client:
# 准备请求头
forward_headers = {
"X-Goog-Upload-Protocol": headers.get("x-goog-upload-protocol", "resumable"),
"X-Goog-Upload-Command": headers.get("x-goog-upload-command", "start"),
"Content-Type": headers.get("content-type", "application/json"),
}
# 添加其他必要的头
if "x-goog-upload-header-content-length" in headers:
forward_headers["X-Goog-Upload-Header-Content-Length"] = headers["x-goog-upload-header-content-length"]
if "x-goog-upload-header-content-type" in headers:
forward_headers["X-Goog-Upload-Header-Content-Type"] = headers["x-goog-upload-header-content-type"]
# 发送请求
response = await client.post(
"https://generativelanguage.googleapis.com/upload/v1beta/files",
headers=forward_headers,
content=body,
params={"key": api_key}
)
if response.status_code != 200:
logger.error(f"Upload initialization failed: {response.status_code} - {response.text}")
raise HTTPException(status_code=response.status_code, detail="Upload initialization failed")
# 获取上传 URL
upload_url = response.headers.get("x-goog-upload-url")
if not upload_url:
raise HTTPException(status_code=500, detail="No upload URL in response")
logger.info(f"Original upload URL from Google: {upload_url}")
# 儲存上傳資訊到 headers 中,供後續使用
# 不在這裡創建數據庫記錄,等到上傳完成後再創建
logger.info(f"Upload initialized with API key: {api_key[:8]}...{api_key[-4:]}")
# 解析响应 - 初始化响应可能是空的
response_data = {}
# 從請求體中解析文件信息(如果有)
display_name = ""
if body:
try:
request_data = json.loads(body)
display_name = request_data.get("displayName", "")
except:
pass
# 從 upload URL 中提取 upload_id
import urllib.parse
parsed_url = urllib.parse.urlparse(upload_url)
query_params = urllib.parse.parse_qs(parsed_url.query)
upload_id = query_params.get('upload_id', [None])[0]
if upload_id:
# 儲存上傳會話信息,使用 upload_id 作為 key
async with _upload_sessions_lock:
_upload_sessions[upload_id] = {
"api_key": api_key,
"user_token": user_token,
"display_name": display_name,
"mime_type": headers.get("x-goog-upload-header-content-type", "application/octet-stream"),
"size_bytes": int(headers.get("x-goog-upload-header-content-length", "0")),
"created_at": datetime.now(timezone.utc),
"upload_url": upload_url
}
logger.info(f"Stored upload session for upload_id={upload_id}: api_key={api_key[:8]}...{api_key[-4:]}")
logger.debug(f"Total active sessions: {len(_upload_sessions)}")
else:
logger.warning(f"No upload_id found in upload URL: {upload_url}")
# 定期清理過期的會話(超過1小時)
asyncio.create_task(self._cleanup_expired_sessions())
# 替換 Google 的 URL 為我們的代理 URL
proxy_upload_url = upload_url
if request_host:
# 原始: https://generativelanguage.googleapis.com/upload/v1beta/files?key=AIzaSyDc...&upload_id=xxx&upload_protocol=resumable
# 替換為: http://request-host/upload/v1beta/files?key=sk-123456&upload_id=xxx&upload_protocol=resumable
# 先替換域名
proxy_upload_url = upload_url.replace(
"https://generativelanguage.googleapis.com",
request_host.rstrip('/')
)
# 再替換 key 參數
import re
# 匹配 key=xxx 參數
key_pattern = r'(\?|&)key=([^&]+)'
match = re.search(key_pattern, proxy_upload_url)
if match:
# 替換為我們的 token
proxy_upload_url = proxy_upload_url.replace(
f"{match.group(1)}key={match.group(2)}",
f"{match.group(1)}key={user_token}"
)
logger.info(f"Replaced upload URL: {upload_url} -> {proxy_upload_url}")
return response_data, {
"X-Goog-Upload-URL": proxy_upload_url,
"X-Goog-Upload-Status": "active"
}
except HTTPException:
raise
except Exception as e:
logger.error(f"Failed to initialize upload: {str(e)}")
raise HTTPException(status_code=500, detail=f"Internal error: {str(e)}")
async def _cleanup_expired_sessions(self):
"""清理過期的上傳會話"""
try:
async with _upload_sessions_lock:
now = datetime.now(timezone.utc)
expired_keys = []
for key, session in _upload_sessions.items():
if now - session["created_at"] > timedelta(hours=1):
expired_keys.append(key)
for key in expired_keys:
del _upload_sessions[key]
if expired_keys:
logger.info(f"Cleaned up {len(expired_keys)} expired upload sessions")
except Exception as e:
logger.error(f"Error cleaning up upload sessions: {str(e)}")
async def get_upload_session(self, key: str) -> Optional[Dict[str, Any]]:
"""獲取上傳會話信息(支持 upload_id 或完整 URL"""
async with _upload_sessions_lock:
# 先嘗試直接查找
session = _upload_sessions.get(key)
if session:
logger.debug(f"Found session by direct key {key}")
return session
# 如果是 URL,嘗試提取 upload_id
if key.startswith("http"):
import urllib.parse
parsed_url = urllib.parse.urlparse(key)
query_params = urllib.parse.parse_qs(parsed_url.query)
upload_id = query_params.get('upload_id', [None])[0]
if upload_id:
session = _upload_sessions.get(upload_id)
if session:
logger.debug(f"Found session by upload_id {upload_id} from URL")
return session
logger.debug(f"No session found for key: {key}")
return None
async def get_file(self, file_name: str, user_token: str) -> FileMetadata:
"""
获取文件信息
Args:
file_name: 文件名称 (格式: files/{file_id})
user_token: 用户令牌
Returns:
FileMetadata: 文件元数据
"""
try:
# 查询文件记录
file_record = await db_services.get_file_record_by_name(file_name)
if not file_record:
raise HTTPException(status_code=404, detail="File not found")
# 检查是否过期
expiration_time = datetime.fromisoformat(str(file_record["expiration_time"]))
# 如果是 naive datetime,假设为 UTC
if expiration_time.tzinfo is None:
expiration_time = expiration_time.replace(tzinfo=timezone.utc)
if expiration_time <= datetime.now(timezone.utc):
raise HTTPException(status_code=404, detail="File has expired")
# 使用原始 API key 获取文件信息
api_key = file_record["api_key"]
async with AsyncClient() as client:
response = await client.get(
f"https://generativelanguage.googleapis.com/v1beta/{file_name}",
params={"key": api_key}
)
if response.status_code != 200:
logger.error(f"Failed to get file: {response.status_code} - {response.text}")
raise HTTPException(status_code=response.status_code, detail="Failed to get file")
file_data = response.json()
# 檢查並更新文件狀態
google_state = file_data.get("state", "PROCESSING")
if google_state != file_record.get("state", "").value if file_record.get("state") else None:
logger.info(f"File state changed from {file_record.get('state')} to {google_state}")
# 更新數據庫中的狀態
if google_state == "ACTIVE":
await db_services.update_file_record_state(
file_name=file_name,
state=FileState.ACTIVE,
update_time=datetime.now(timezone.utc)
)
elif google_state == "FAILED":
await db_services.update_file_record_state(
file_name=file_name,
state=FileState.FAILED,
update_time=datetime.now(timezone.utc)
)
# 构建响应
return FileMetadata(
name=file_data["name"],
displayName=file_data.get("displayName"),
mimeType=file_data["mimeType"],
sizeBytes=str(file_data["sizeBytes"]),
createTime=file_data["createTime"],
updateTime=file_data["updateTime"],
expirationTime=file_data["expirationTime"],
sha256Hash=file_data.get("sha256Hash"),
uri=file_data["uri"],
state=google_state
)
except HTTPException:
raise
except Exception as e:
logger.error(f"Failed to get file {file_name}: {str(e)}")
raise HTTPException(status_code=500, detail=f"Internal error: {str(e)}")
async def list_files(
self,
page_size: int = 10,
page_token: Optional[str] = None,
user_token: Optional[str] = None
) -> ListFilesResponse:
"""
列出文件
Args:
page_size: 每页大小
page_token: 分页标记
user_token: 用户令牌(可选,如果提供则只返回该用户的文件)
Returns:
ListFilesResponse: 文件列表响应
"""
try:
logger.debug(f"list_files called with page_size={page_size}, page_token={page_token}")
# 从数据库获取文件列表
files, next_page_token = await db_services.list_file_records(
user_token=user_token,
page_size=page_size,
page_token=page_token
)
logger.debug(f"Database returned {len(files)} files, next_page_token={next_page_token}")
# 转换为响应格式
file_list = []
for file_record in files:
file_list.append(FileMetadata(
name=file_record["name"],
displayName=file_record.get("display_name"),
mimeType=file_record["mime_type"],
sizeBytes=str(file_record["size_bytes"]),
createTime=file_record["create_time"].isoformat() + "Z",
updateTime=file_record["update_time"].isoformat() + "Z",
expirationTime=file_record["expiration_time"].isoformat() + "Z",
sha256Hash=file_record.get("sha256_hash"),
uri=file_record["uri"],
state=file_record["state"].value if file_record.get("state") else "ACTIVE"
))
response = ListFilesResponse(
files=file_list,
nextPageToken=next_page_token
)
logger.debug(f"Returning response with {len(response.files)} files, nextPageToken={response.nextPageToken}")
return response
except Exception as e:
logger.error(f"Failed to list files: {str(e)}")
raise HTTPException(status_code=500, detail=f"Internal error: {str(e)}")
async def delete_file(self, file_name: str, user_token: str) -> bool:
"""
删除文件
Args:
file_name: 文件名称
user_token: 用户令牌
Returns:
bool: 是否删除成功
"""
try:
# 查询文件记录
file_record = await db_services.get_file_record_by_name(file_name)
if not file_record:
raise HTTPException(status_code=404, detail="File not found")
# 使用原始 API key 删除文件
api_key = file_record["api_key"]
async with AsyncClient() as client:
response = await client.delete(
f"https://generativelanguage.googleapis.com/v1beta/{file_name}",
params={"key": api_key}
)
if response.status_code not in [200, 204]:
logger.error(f"Failed to delete file: {response.status_code} - {response.text}")
# 如果 API 删除失败,但文件已过期,仍然删除数据库记录
expiration_time = datetime.fromisoformat(str(file_record["expiration_time"]))
if expiration_time.tzinfo is None:
expiration_time = expiration_time.replace(tzinfo=timezone.utc)
if expiration_time <= datetime.now(timezone.utc):
await db_services.delete_file_record(file_name)
return True
raise HTTPException(status_code=response.status_code, detail="Failed to delete file")
# 删除数据库记录
await db_services.delete_file_record(file_name)
return True
except HTTPException:
raise
except Exception as e:
logger.error(f"Failed to delete file {file_name}: {str(e)}")
raise HTTPException(status_code=500, detail=f"Internal error: {str(e)}")
async def check_file_state(self, file_name: str, api_key: str) -> str:
"""
檢查並更新文件狀態
Args:
file_name: 文件名稱
api_key: API密鑰
Returns:
str: 當前狀態
"""
try:
async with AsyncClient() as client:
response = await client.get(
f"https://generativelanguage.googleapis.com/v1beta/{file_name}",
params={"key": api_key}
)
if response.status_code != 200:
logger.error(f"Failed to check file state: {response.status_code}")
return "UNKNOWN"
file_data = response.json()
google_state = file_data.get("state", "PROCESSING")
# 更新數據庫狀態
if google_state == "ACTIVE":
await db_services.update_file_record_state(
file_name=file_name,
state=FileState.ACTIVE,
update_time=datetime.now(timezone.utc)
)
elif google_state == "FAILED":
await db_services.update_file_record_state(
file_name=file_name,
state=FileState.FAILED,
update_time=datetime.now(timezone.utc)
)
return google_state
except Exception as e:
logger.error(f"Failed to check file state: {str(e)}")
return "UNKNOWN"
async def cleanup_expired_files(self) -> int:
"""
清理过期文件
Returns:
int: 清理的文件数量
"""
try:
# 获取过期文件
expired_files = await db_services.delete_expired_file_records()
if not expired_files:
return 0
# 尝试从 Gemini API 删除文件
for file_record in expired_files:
try:
api_key = file_record["api_key"]
file_name = file_record["name"]
async with AsyncClient() as client:
await client.delete(
f"https://generativelanguage.googleapis.com/v1beta/{file_name}",
params={"key": api_key}
)
except Exception as e:
# 记录错误但继续处理其他文件
logger.error(f"Failed to delete file {file_record['name']} from API: {str(e)}")
return len(expired_files)
except Exception as e:
logger.error(f"Failed to cleanup expired files: {str(e)}")
return 0
# 单例实例
_files_service_instance: Optional[FilesService] = None
async def get_files_service() -> FilesService:
"""获取文件服务单例实例"""
global _files_service_instance
if _files_service_instance is None:
_files_service_instance = FilesService()
return _files_service_instance