memory-bank/techContext.md

技术背景 (techContext.md)

使用的技术

• **Python 3.9+**：作为主要的开发语言。
• **FastAPI 0.120.0+**：高性能的 Python Web 框架，用于构建 API 代理。
• Uvicorn：ASGI 服务器，用于运行 FastAPI 应用程序。
• **httpx 0.28.1+**：异步 HTTP 客户端，用于向目标 API 发送请求。
• python-dotenv：用于从 .env 文件加载环境变量。

开发环境设置

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

   conda create -n airs python=3.9
   conda activate airs
   

2. 依赖安装：通过 requirements.txt 安装所有项目依赖。

   pip install -r requirements.txt
   

3. 环境变量：在项目根目录创建 .env 文件，并配置以下变量：

   GEMINI_API_KEY="YOUR_GEMINI_API_KEY"
   GEMINI_BASE_URL="https://generativelanguage.googleapis.com/v1beta/openai"
   

   请将 YOUR_GEMINI_API_KEY 替换为您的实际 Gemini API 密钥。

技术约束

• FastAPI 路由匹配顺序：通用路由 /{path:path} 必须放在特定路由（如 /health）之后，否则会优先匹配通用路由。
• 异步 HTTP 请求：由于 FastAPI 是异步框架，使用 httpx 这样的异步 HTTP 客户端是最佳实践，以避免阻塞事件循环。
• API 密钥安全：API 密钥不应直接硬编码在代码中，而应通过环境变量安全管理。
• Hugging Face Spaces 部署：部署到 Hugging Face Spaces 时，需要确保 .env 文件中的环境变量已正确配置，并且 app.py 中的 uvicorn 启动命令与 Space 的配置兼容。

依赖管理

项目依赖通过 requirements.txt 文件进行管理：

fastapi
uvicorn[standard]
httpx
python-dotenv

工具使用模式

• **uvicorn**：用于本地开发和部署时启动 FastAPI 应用。 uvicorn app:app --host 0.0.0.0 --port 7860 --reload
• **pip / pip3**：用于安装 Python 依赖。
• curl / Postman：用于测试 API 代理功能。
• **.clinerules**：用于配置 Cline 的自定义指令，例如自动激活 conda 环境。