Add Docker SDK configuration to README

README.md

@@ -1,478 +1,7 @@
-# Z.AI OpenAI API 代理服务
-
-![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)
-![Python: 3.8+](https://img.shields.io/badge/python-3.8+-green.svg)
-![FastAPI](https://img.shields.io/badge/framework-FastAPI-009688.svg)
-![Version: 1.2.0](https://img.shields.io/badge/version-1.2.0-brightgreen.svg)
-
-轻量级 OpenAI API 兼容代理服务，通过 Claude Code Router 接入 Z.AI，支持 GLM-4.6 系列模型的完整功能。
-
-## ✨ 核心特性
-
-- 🔌 **完全兼容 OpenAI API** - 无缝集成现有应用
-- 🤖 **Claude Code 支持** - 通过 Claude Code Router 接入 Claude Code (**CCR 工具请升级到 v1.0.47 以上**)
-- 🚀 **高性能流式响应** - Server-Sent Events (SSE) 支持
-- 🛠️ **增强工具调用** - 改进的 Function Call 实现
-- 🧠 **思考模式支持** - 智能处理模型推理过程
-- 🔍 **搜索模型集成** - GLM-4.5-Search 网络搜索能力
-- 🐳 **Docker 部署** - 一键容器化部署
-- 🛡️ **会话隔离** - 匿名模式保护隐私
-- 🔧 **灵活配置** - 环境变量灵活配置
-- 📊 **多模型映射** - 智能上游模型路由
-
-## 🚀 快速开始
-
-### 环境要求
-
-- Python 3.8+
-- pip 或 uv (推荐)
-
-### 安装运行
-
-```bash
-# 克隆项目
-git clone https://github.com/ZyphrZero/z.ai2api_python.git
-cd z.ai2api_python
-
-# 使用 uv (推荐)
-curl -LsSf https://astral.sh/uv/install.sh | sh
-uv sync
-uv run python main.py
-
-# 或使用 pip (推荐使用清华源)
-pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
-python main.py
-```
-
-服务启动后访问：http://localhost:8080/docs
-
-### 基础使用
-
-#### OpenAI API 客户端
-
-```python
-import openai
-
-# 初始化客户端
-client = openai.OpenAI(
-    base_url="http://localhost:8080/v1",
-    api_key="your-auth-token"  # 替换为你的 AUTH_TOKEN
-)
-
-# 普通对话
-response = client.chat.completions.create(
-    model="GLM-4.5",
-    messages=[{"role": "user", "content": "你好，介绍一下 Python"}],
-    stream=False
-)
-
-print(response.choices[0].message.content)
-```
-
-### Docker 部署
-
-```bash
-cd deploy
-docker-compose up -d
-```
-
-## 📖 详细指南
-
-### 支持的模型
-
-| 模型               | 上游 ID       | 描述        | 特性                   |
-| ------------------ | ------------- | ----------- | ---------------------- |
-| `GLM-4.5`          | 0727-360B-API | 标准模型    | 通用对话，平衡性能     |
-| `GLM-4.5-Thinking` | 0727-360B-API | 思考模型    | 显示推理过程，透明度高 |
-| `GLM-4.5-Search`   | 0727-360B-API | 搜索模型    | 实时网络搜索，信息更新 |
-| `GLM-4.5-Air`      | 0727-106B-API | 轻量模型    | 快速响应，高效推理     |
-| `GLM-4.5V`         | glm-4.5v      | ❌ 暂不支持 |                        |
-
-### Function Call 功能
-
-```python
-# 定义工具
-tools = [{
-    "type": "function",
-    "function": {
-        "name": "get_weather",
-        "description": "获取天气信息",
-        "parameters": {
-            "type": "object",
-            "properties": {
-                "city": {"type": "string", "description": "城市名称"}
-            },
-            "required": ["city"]
-        }
-    }
-}]
-
-# 使用工具
-response = client.chat.completions.create(
-    model="GLM-4.6",
-    messages=[{"role": "user", "content": "北京天气怎么样？"}],
-    tools=tools,
-    tool_choice="auto"
-)
-```
-
-### 流式响应
-
-```python
-response = client.chat.completions.create(
-    model="GLM-4.6-Thinking",
-    messages=[{"role": "user", "content": "解释量子计算"}],
-    stream=True
-)
-
-for chunk in response:
-    content = chunk.choices[0].delta.content
-    reasoning = chunk.choices[0].delta.reasoning_content
-
-    if content:
-        print(content, end="")
-    if reasoning:
-        print(f"\n🤔 思考: {reasoning}\n")
-```
-
-## ⚙️ 配置说明
-
-### 环境变量配置
-
-| 变量名                | 默认值                                    | 说明                   |
-| --------------------- | ----------------------------------------- | ---------------------- |
-| `AUTH_TOKEN`          | `sk-your-api-key`                         | 客户端认证密钥         |
-| `API_ENDPOINT`        | `https://chat.z.ai/api/chat/completions`  | 上游 API 地址          |
-| `LISTEN_PORT`         | `8080`                                    | 服务监听端口           |
-| `DEBUG_LOGGING`       | `true`                                    | 调试日志开关           |
-| `THINKING_PROCESSING` | `think`                                   | 思考内容处理策略       |
-| `ANONYMOUS_MODE`      | `true`                                    | 匿名模式开关           |
-| `TOOL_SUPPORT`        | `true`                                    | Function Call 功能开关 |
-| `SKIP_AUTH_TOKEN`     | `false`                                   | 跳过认证令牌验证       |
-| `SCAN_LIMIT`          | `200000`                                  | 扫描限制               |
-| `BACKUP_TOKEN`        | `eyJhbGciO...`                            | 固定访问令牌，多个以','分隔|
-| `TOKEN_FILE_PATH`     | `./tokens.txt`                            | Token文件路径          |
-| `TOKEN_MAX_FAILURES`  | `3`                                       | Token最大失败次数      |
-| `TOKEN_RELOAD_INTERVAL`| `60`                                     | Token重载间隔(秒)      |
-
-### 思考内容处理策略
-
-- `think` - 转换为 `<thinking>` 标签（OpenAI 兼容）
-- `strip` - 移除思考内容
-- `raw` - 保留原始格式
-
-## 🔑 Token 轮询管理
-
-系统支持智能 Token 轮询管理，可以在多个 Token 之间自动切换，实现负载均衡和容错处理。
-
-### Token 来源
-
-系统按以下优先级加载 Token：
-
-1. **tokens.txt 文件** - 在项目根目录创建 `tokens.txt` 文件，每行一个 Token
-2. **BACKUP_TOKEN 环境变量** - 支持多个 Token，以逗号分隔
-
-### tokens.txt 文件格式
-
-```
-# 这是注释，会被忽略
-sk-your-first-token-here
-sk-your-second-token-here
-sk-your-third-token-here
-```
-
-### BACKUP_TOKEN 环境变量格式
-
-```bash
-# 单个 Token
-BACKUP_TOKEN=sk-your-token-here
-
-# 多个 Token（以逗号分隔）
-BACKUP_TOKEN=sk-first-token,sk-second-token,sk-third-token
-```
-
-### Token 轮询机制
-
-- **轮询策略**：采用轮询（Round-Robin）算法，依次使用每个可用 Token
-- **失败处理**：当 Token 失败时，系统会标记失败次数，达到最大失败次数后自动禁用
-- **自动恢复**：禁用的 Token 会在重新加载时重置状态
-- **去重机制**：自动去除重复的 Token，确保每个 Token 只使用一次
-- **状态保持**：保留已有 Token 的失败计数和使用状态
-
-### Token 配置参数
-
-| 参数                 | 默认值 | 说明                         |
-| -------------------- | ------ | ---------------------------- |
-| `TOKEN_FILE_PATH`    | `./tokens.txt` | Token 文件路径               |
-| `TOKEN_MAX_FAILURES` | `3`    | Token 最大失败次数           |
-| `TOKEN_RELOAD_INTERVAL` | `60`  | Token 重载间隔（秒）         |
-
-### 使用示例
-
-#### 1. 仅使用 tokens.txt
-
-创建 `tokens.txt` 文件：
-```
-sk-token-1
-sk-token-2
-sk-token-3
-```
-
-#### 2. 仅使用 BACKUP_TOKEN
-
-在 `.env` 文件中配置：
-```env
-BACKUP_TOKEN=sk-token-1,sk-token-2,sk-token-3
-```
-
-#### 3. 同时使用 tokens.txt 和 BACKUP_TOKEN
-
-系统会合并两个来源的 Token，自动去重：
-
-- `tokens.txt` 包含：`sk-token-1`, `sk-token-2`
-- `BACKUP_TOKEN` 包含：`sk-token-2`, `sk-token-3`
-- 最终 Token 池：`sk-token-1`, `sk-token-2`, `sk-token-3`
-
-### Token 状态监控
-
-系统提供了 Token 状态统计接口，可以查看：
-
-- Token 总数
-- 活跃 Token 数量
-- 失败 Token 数量
-- 每个 Token 的详细信息（预览、状态、失败次数等）
-
-### 最佳实践
-
-1. **Token 分散**：将 Token 分散存储在 `tokens.txt` 和 `BACKUP_TOKEN` 中
-2. **定期更新**：定期检查 Token 有效性，及时替换失效的 Token
-3. **监控状态**：关注 Token 失败情况，及时调整配置
-4. **合理设置**：根据 API 调用频率调整 `TOKEN_MAX_FAILURES` 和 `TOKEN_RELOAD_INTERVAL`
-
-## 🎯 使用场景
-
-### 1. AI 应用开发
-
-```python
-# 集成到现有应用
-from openai import OpenAI
-
-client = OpenAI(
-    base_url="http://localhost:8080/v1",
-    api_key="your-token"
-)
-
-# 智能客服
-def chat_with_ai(message):
-    response = client.chat.completions.create(
-        model="GLM-4.6",
-        messages=[{"role": "user", "content": message}]
-    )
-    return response.choices[0].message.content
-```
-
-### 2. 工具调用集成
-
-```python
-# 结合外部 API
-def call_external_api(tool_name, arguments):
-    # 执行实际工具调用
-    return result
-
-# 处理工具调用
-if response.choices[0].message.tool_calls:
-    for tool_call in response.choices[0].message.tool_calls:
-        result = call_external_api(
-            tool_call.function.name,
-            json.loads(tool_call.function.arguments)
-        )
-        # 将结果返回给模型继续对话
-```
-
-## ❓ 常见问题
-
-**Q: 如何获取 AUTH_TOKEN？**
-A: `AUTH_TOKEN` 为自己自定义的 api key，在环境变量中配置，需要保证客户端与服务端一致。
-
-**Q: 如何通过 Claude Code 使用本服务？**
-
-A: 创建 [zai.js](https://gist.githubusercontent.com/musistudio/b35402d6f9c95c64269c7666b8405348/raw/f108d66fa050f308387938f149a2b14a295d29e9/gistfile1.txt) 这个 ccr 插件放在`./.claude-code-router/plugins`目录下，配置 `./.claude-code-router/config.json` 指向本服务地址，使用 `AUTH_TOKEN` 进行认证。
-
-示例配置：
-
-```json
-{
-  "LOG": false,
-  "LOG_LEVEL": "debug",
-  "CLAUDE_PATH": "",
-  "HOST": "127.0.0.1",
-  "PORT": 3456,
-  "APIKEY": "",
-  "API_TIMEOUT_MS": "600000",
-  "PROXY_URL": "",
-  "transformers": [
-    {
-      "name": "zai",
-      "path": "C:\\Users\\Administrator\\.claude-code-router\\plugins\\zai.js",
-      "options": {}
-    }
-  ],
-  "Providers": [
-    {
-      "name": "GLM",
-      "api_base_url": "http://127.0.0.1:8080/v1/chat/completions",
-      "api_key": "sk-your-api-key",
-      "models": ["GLM-4.5", "GLM-4.5-Air"],
-      "transformers": {
-        "use": ["zai"]
-      }
-    }
-  ],
-  "StatusLine": {
-    "enabled": false,
-    "currentStyle": "default",
-    "default": {
-      "modules": []
-    },
-    "powerline": {
-      "modules": []
-    }
-  },
-  "Router": {
-    "default": "GLM,GLM-4.5",
-    "background": "GLM,GLM-4.5",
-    "think": "GLM,GLM-4.5",
-    "longContext": "GLM,GLM-4.5",
-    "longContextThreshold": 60000,
-    "webSearch": "GLM,GLM-4.5",
-    "image": "GLM,GLM-4.5"
-  },
-  "CUSTOM_ROUTER_PATH": ""
-}
-```
-
-**Q: 匿名模式是什么？**  
-A: 匿名模式使用临时 token，避免对话历史共享，保护隐私。
-
-**Q: Function Call 如何工作？**  
-A: 通过智能提示注入实现，将工具定义转换为系统提示。
-
-**Q: 支持哪些 OpenAI 功能？**  
-A: 支持聊天完成、模型列表、流式响应、工具调用等核心功能。
-
-**Q: Function Call 如何优化？**  
-A: 改进了工具调用的请求响应结构，支持更复杂的工具链调用和并行执行。
-
-**Q: 如何选择合适的模型？**  
-A:
-
-- **GLM-4.5**: 通用场景，性能和效果平衡
-- **GLM-4.5-Thinking**: 需要了解推理过程的场景
-- **GLM-4.5-Search**: 需要实时信息的场景
-- **GLM-4.5-Air**: 高并发、低延迟要求的场景
-- **GLM-4.6**: 最新模型，性能和效果最佳
-- **GLM-4.6-Thinking**: 模型推理过程
-
-
-**Q: 如何自定义配置？**  
-A: 通过环境变量配置，推荐使用 `.env` 文件。
-
-## 🔑 获取 Z.ai API Token
-
-要使用完整的多模态功能，需要获取正式的 Z.ai API Token：
-
-### 方式 1: 通过 Z.ai 网站
-
-1. 访问 [Z.ai 官网](https://chat.z.ai)
-2. 注册账户并登录，进入 [Z.ai API Keys](https://z.ai/manage-apikey/apikey-list) 设置页面，在该页面设置 _**个人 API Token**_
-3. 将 Token 放置在 `BACKUP_TOKEN` 环境变量中
-
-### 方式 2: 浏览器开发者工具（临时方案）
-
-1. 打开 [Z.ai 聊天界面](https://chat.z.ai)
-2. 按 F12 打开开发者工具
-3. 切换到 "Application" 或 "存储" 标签
-4. 查看 Local Storage 中的认证 token
-5. 复制 token 值设置为环境变量
-
-> ⚠️ **注意**: 方式 2 获取的 token 可能有时效性，建议使用方式 1 获取长期有效的 API Token。  
-> ❗ **重要提示**: 多模态模型需要**官方 Z.ai API 非匿名 Token**，匿名 token 不支持多媒体处理。
-
-## 🛠️ 技术栈
-
-| 组件            | 技术                                                                              | 版本    | 说明                                       |
-| --------------- | --------------------------------------------------------------------------------- | ------- | ------------------------------------------ |
-| **Web 框架**    | [FastAPI](https://fastapi.tiangolo.com/)                                          | 0.104.1 | 高性能异步 Web 框架，支持自动 API 文档生成 |
-| **ASGI 服务器** | [Granian](https://github.com/emmett-framework/granian)                            | 2.5.2   | 基于 Rust 的高性能 ASGI 服务器，支持热重载 |
-| **HTTP 客户端** | [Requests](https://requests.readthedocs.io/)                                      | 2.32.5  | 简洁易用的 HTTP 库，用于上游 API 调用      |
-| **数据验证**    | [Pydantic](https://pydantic.dev/)                                                 | 2.11.7  | 类型安全的数据验证与序列化                 |
-| **配置管理**    | [Pydantic Settings](https://docs.pydantic.dev/latest/concepts/pydantic_settings/) | 2.10.1  | 基于 Pydantic 的配置管理                   |
-
-## 🏗️ 技术架构
-
-```
-┌──────────────┐      ┌─────────────────────────┐      ┌─────────────────┐
-│   OpenAI     │      │                         │      │                 │
-│  Client      │────▶│    FastAPI Server       │────▶│   Z.AI API      │
-└──────────────┘      │                         │      │                 │
-┌──────────────┐      │ ┌─────────────────────┐ │      │ ┌─────────────┐ │
-│ Claude Code  │      │ │ /v1/chat/completions│ │      │ │0727-360B-API│ │
-│   Router     │────▶│ └─────────────────────┘ │      │ └─────────────┘ │
-└──────────────┘      │ ┌─────────────────────┐ │      │ ┌─────────────┐ │
-                      ��� │    /v1/models       │ │────▶│ │0727-106B-API│ │
-                      │ └─────────────────────┘ │      │ └─────────────┘ │
-                      │ ┌─────────────────────┐ │      │                 │
-                      │ │  Enhanced Tools     │ │      └─────────────────┘
-                      │ └─────────────────────┘ │
-                      └─────────────────────────┘
-                           OpenAI Compatible API
-```
-
-### 项目结构
-
-```
-z.ai2api_python/
-├── app/
-│   ├── core/
-│   │   ├── __init__.py
-│   │   ├── config.py          # 配置管理
-│   │   ├── openai.py          # OpenAI API 实现
-│   │   └── response_handlers.py  # 响应处理器
-│   ├── models/
-│   │   ├── __init__.py
-│   │   └── schemas.py         # Pydantic 模型定义
-│   ├── utils/
-│   │   ├── __init__.py
-│   │   ├── helpers.py         # 辅助函数
-│   │   ├── tools.py           # 增强工具调用处理
-│   │   └── sse_parser.py      # SSE 流式解析器
-│   └── __init__.py
-├── tests/                     # 单元测试
-├── deploy/                    # Docker 部署配置
-├── main.py                    # FastAPI 应用入口
-├── requirements.txt           # Python 依赖
-├── .env.example              # 环境变量示例
-└── README.md                  # 项目文档
-```
-
-## 🤝 贡献指南
-
-我们欢迎所有形式的贡献！
-请确保代码符合 PEP 8 规范，并更新相关文档。
-
-## 📄 许可证
-
-本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。
-
-## ⚠️ 免责声明
-
-- 本项目与 Z.AI 官方无关
-- 使用前请确保遵守 Z.AI 服务条款
-- 请勿用于商业用途或违反使用条款的场景
-- 项目仅供学习和研究使用
-
 ---
-
-<div align="center">
-Made with ❤️ by the community
-</div>
+title: Z.AI API
+emoji: 🚀
+colorFrom: blue
+colorTo: green
+sdk: docker
+---