Update README.md

README.md

@@ -1,106 +1,49 @@
+# Z.AI OpenAI API 代理服务
 
-## 项目简介
-
-这是一个为 Z.ai 提供 OpenAI API 兼容接口的 Python 代理服务，允许开发者通过标准的 OpenAI API 格式访问 Z.ai 的 GLM-4.5 模型。
-
-## 主要特性
-
-- **OpenAI API 兼容**：完整支持 `/v1/chat/completions` 和 `/v1/models` 端点
-- **流式响应支持**：完整实现 Server-Sent Events (SSE) 流式传输
-- **思考内容处理**：提供多种策略处理模型的思考过程（`<details>` 标签）
-- **匿名会话支持**：可选使用匿名 token 避免共享对话历史
-- **多种模型支持**：支持 GLM-4.5 基础版、思考版和搜索版
-- **调试模式**：详细的请求/响应日志记录，便于开发调试
-- **CORS 支持**：内置跨域资源共享支持
-- **Function Call 支持**：完整支持 OpenAI 格式的工具调用功能，通过智能提示注入实现，支持流式响应时的工具调用缓冲机制
-
-## 使用场景
-
-- 将 Z.ai 集成到支持 OpenAI API 的应用程序中
-- 开发需要同时使用多个 AI 服务的应用
-- 测试和评估 GLM-4.5 模型的能力
-- 需要流式响应或思考内容的 AI 应用开发
-
-## 快速开始
-
-### 使用 uv (推荐)
-
-1. 安装 uv：
-   ```bash
-   # macOS/Linux
-   curl -LsSf https://astral.sh/uv/install.sh | sh
-   # Windows (PowerShell)
-   powershell -c "irm https://astral.sh/uv/install.sh | iex"
-   ```
-
-2. 同步依赖：
-   ```bash
-   uv sync
-   ```
-
-3. 运行服务：
-   ```bash
-   uv run python main.py
-   ```
-
-### 使用 pip
-
-1. 安装依赖：
-   ```bash
-   pip install -r requirements.txt
-   ```
-
-2. 配置服务（可选）：
-   编辑 `main.py` 中的 `ServerConfig` 类以调整服务行为：
-   - `AUTH_TOKEN`: 客户端 API Key 密钥
-   - `API_ENDPOINT`: Z.ai 上游 API 地址
-   - `BACKUP_TOKEN`: 固定认证 token（匿名模式失败时使用）
-   - `LISTEN_PORT`: 服务监听端口
-   - `DEBUG_LOGGING`: 调试模式开关
-   - `THINKING_PROCESSING`: 思考内容处理策略
-   - `ANONYMOUS_MODE`: 匿名模式开关
-   - `TOOL_SUPPORT`: Function Call 功能开关
-
-3. 运行服务：
-   ```bash
-   python main.py
-   ```
-
-   服务启动后，可以访问 http://localhost:8080/docs 查看自动生成的 Swagger API 文档
-
-4. 使用 OpenAI 客户端库调用：
-   ```python
-   import openai
-
-   # 初始化客户端
-   client = openai.OpenAI(
-       base_url="http://localhost:8080/v1",
-       api_key="sk-your-api-key"
-   )
-
-   # 流式调用示例
-   response = client.chat.completions.create(
-       model="GLM-4.5",  # 可选: "GLM-4.5-Thinking", "GLM-4.5-Search"
-       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")
-   ```
-
-   注意：请将 `api_key` 替换为您在 `main.py` 中配置的 `AUTH_TOKEN` 值。
-
-### Function Call 使用示例
-
-本项目完整支持 OpenAI 格式的工具调用功能，包括流式和非流式响应。实现原理是将 OpenAI 的工具定义转换为特殊的系统提示，让模型理解并生成符合格式的工具调用。
-
-#### 基本工具调用
+![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)
+
+为 Z.AI 提供 OpenAI API 兼容接口的轻量级代理服务，支持 GLM-4.5 系列模型的完整功能。
+
+## ✨ 核心特性
+
+- 🔌 **完全兼容 OpenAI API** - 无缝集成现有应用
+- 🚀 **高性能流式响应** - 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 requirement.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
+python main.py
+```
+
+服务启动后访问：http://localhost:8080/docs
+
+### 基础使用
 
 ```python
 import openai
@@ -108,281 +51,207 @@ import openai
 # 初始化客户端
 client = openai.OpenAI(
     base_url="http://localhost:8080/v1",
-    api_key="sk-your-api-key"
+    api_key="your-auth-token"  # 替换为你的 AUTH_TOKEN
 )
 
-# 定义天气查询工具
-tools = [
-    {
-        "type": "function",
-        "function": {
-            "name": "get_weather",
-            "description": "获取指定城市的天气信息",
-            "parameters": {
-                "type": "object",
-                "properties": {
-                    "city": {
-                        "type": "string",
-                        "description": "城市名称"
-                    },
-                    "unit": {
-                        "type": "string",
-                        "enum": ["celsius", "fahrenheit"],
-                        "description": "温度单位",
-                        "default": "celsius"
-                    }
-                },
-                "required": ["city"]
-            }
-        }
-    }
-]
-
-# 使用工具调用
+# 普通对话
 response = client.chat.completions.create(
     model="GLM-4.5",
-    messages=[{"role": "user", "content": "北京今天天气怎么样？"}],
-    tools=tools,
-    tool_choice="auto"
+    messages=[{"role": "user", "content": "你好，介绍一下 Python"}],
+    stream=False
 )
 
-message = response.choices[0].message
-if message.tool_calls:
-    print("模型请求调用工具:")
-    for tool_call in message.tool_calls:
-        print(f"工具名称: {tool_call.function.name}")
-        print(f"参数: {tool_call.function.arguments}")
-        print(f"调用ID: {tool_call.id}")
-else:
-    print(f"回复: {message.content}")
+print(response.choices[0].message.content)
 ```
 
-#### 流式工具调用
-
-```python
-# 流式工具调用示例
-response = client.chat.completions.create(
-    model="GLM-4.5",
-    messages=[{"role": "user", "content": "帮我计算 2 的 10 次方"}],
-    tools=[{
-        "type": "function",
-        "function": {
-            "name": "calculate",
-            "description": "执行数学计算",
-            "parameters": {
-                "type": "object",
-                "properties": {
-                    "expression": {
-                        "type": "string",
-                        "description": "数学表达式"
-                    }
-                },
-                "required": ["expression"]
-            }
-        }
-    }],
-    stream=True
-)
-
-# 注意：工具调用模式下，流式响应会缓冲所有内容，
-# 在最后一次性返回工具调用信息
-tool_calls = None
-content = ""
+### Docker 部署
 
-for chunk in response:
-    delta = chunk.choices[0].delta
-    if delta.tool_calls:
-        tool_calls = delta.tool_calls
-    if delta.content:
-        content += delta.content
-
-if tool_calls:
-    print("工具调用:")
-    for tool_call in tool_calls:
-        print(f"函数: {tool_call.function.name}")
-        print(f"参数: {tool_call.function.arguments}")
-else:
-    print("回复:", content)
+```bash
+cd deploy
+docker-compose up -d
 ```
 
-#### 强制使用特定工具
+## 📖 详细指南
 
-```python
-# 强制使用特定工具
-response = client.chat.completions.create(
-    model="GLM-4.5",
-    messages=[{"role": "user", "content": "今天是什么日子"}],
-    tools=[{
-        "type": "function",
-        "function": {
-            "name": "get_current_date",
-            "description": "获取当前日期和时间",
-            "parameters": {
-                "type": "object",
-                "properties": {},
-                "required": []
-            }
-        }
-    }],
-    tool_choice={"type": "function", "function": {"name": "get_current_date"}}
-)
+### 支持的模型
 
-message = response.choices[0].message
-print(f"完成原因: {response.choices[0].finish_reason}")  # tool_calls
-if message.tool_calls:
-    print("工具调用结果:", message.tool_calls[0].function.arguments)
-```
+| 模型 | 描述 | 特性 |
+|------|------|------|
+| `GLM-4.5` | 标准模型 | 通用对话，平衡性能 |
+| `GLM-4.5-Thinking` | 思考模型 | 显示推理过程，透明度高 |
+| `GLM-4.5-Search` | 搜索模型 | 实时网络搜索，信息更新 |
 
-#### 多工具协作
+### Function Call 功能
 
 ```python
-# 定义多个工具
-tools = [
-    {
-        "type": "function",
-        "function": {
-            "name": "search_web",
-            "description": "搜索网络信息",
-            "parameters": {
-                "type": "object",
-                "properties": {
-                    "query": {
-                        "type": "string",
-                        "description": "搜索关键词"
-                    }
-                },
-                "required": ["query"]
-            }
-        }
-    },
-    {
-        "type": "function",
-        "function": {
-            "name": "summarize_text",
-            "description": "总结文本内容",
-            "parameters": {
-                "type": "object",
-                "properties": {
-                    "text": {
-                        "type": "string",
-                        "description": "要总结的文本"
-                    },
-                    "max_length": {
-                        "type": "integer",
-                        "description": "最大长度",
-                        "default": 100
-                    }
-                },
-                "required": ["text"]
-            }
+# 定义工具
+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.5",
-    messages=[{"role": "user", "content": "搜索一下最新的 AI 新闻并总结"}],
+    messages=[{"role": "user", "content": "北京天气怎么样？"}],
     tools=tools,
     tool_choice="auto"
 )
-
-message = response.choices[0].message
-if message.tool_calls:
-    for tool_call in message.tool_calls:
-        print(f"调用工具: {tool_call.function.name}")
-        # 在实际应用中，这里需要执行相应的函数
-        # 并将结果通过工具消息返回给模型
 ```
 
-### 运行 Function Call 演示
+### 流式响应
 
-项目包含一个完整的 Function Call 演示脚本：
+```python
+response = client.chat.completions.create(
+    model="GLM-4.5-Thinking",
+    messages=[{"role": "user", "content": "解释量子计算"}],
+    stream=True
+)
 
-```bash
-python function_call_demo.py
+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")
 ```
 
-该脚本将演示：
-1. 基本的工具调用
-2. 数学计算工具
-3. 强制使用特定工具
-4. 流式工具调用响应
+## ⚙️ 配置说明
 
-### 使用 Docker Compose
+### 环境变量配置
 
-1. 启动服务：
-   ```bash
-   # 在 deploy 目录下运行
-   cd deploy
-   docker-compose up -d
-   ```
+| 变量名 | 默认值 | 说明 |
+|--------|--------|------|
+| `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 功能开关 |
 
-![744X487/QQ20250903-145750.png](https://tc.z.wiki/autoupload/f/KTO6-pUlsq3zQ-YJ9ppdgtiO_OyvX7mIgxFBfDMDErs/20250903/DkjD/744X487/QQ20250903-145750.png)
+### 思考内容处理策略
 
-2. 停止服务：
-   ```bash
-   docker-compose down
-   ```
+- `think` - 转换为 `<thinking>` 标签（OpenAI 兼容）
+- `strip` - 移除思考内容
+- `raw` - 保留原始格式
 
-3. 查看日志：
-   ```bash
-   docker-compose logs -f
-   ```
+## 🎯 使用场景
 
-4. 重新构建并启动：
-   ```bash
-   docker-compose up -d --build
-   ```
+### 1. AI 应用开发
 
-注意：如需修改配置参数（如 API 密钥、端口等），请直接编辑 `main.py` 文件中的 `ServerConfig` 类。
+```python
+# 集成到现有应用
+from openai import OpenAI
 
-![1830X875/微信图片_20250903145327_21624_1.png](https://tc-new.z.wiki/autoupload/f/KTO6-pUlsq3zQ-YJ9ppdgtiO_OyvX7mIgxFBfDMDErs/20250903/AF2F/1830X875/%E5%BE%AE%E4%BF%A1%E5%9B%BE%E7%89%87_20250903145327_21624_1.png)
+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.5",
+        messages=[{"role": "user", "content": message}]
+    )
+    return response.choices[0].message.content
+```
+
+### 2. 多模型对比测试
+
+```python
+models = ["GLM-4.5", "GLM-4.5-Thinking", "GLM-4.5-Search"]
+
+for model in models:
+    response = client.chat.completions.create(
+        model=model,
+        messages=[{"role": "user", "content": "什么是机器学习？"}]
+    )
+    print(f"\n=== {model} ===")
+    print(response.choices[0].message.content)
+```
+
+### 3. 工具调用集成
+
+```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，在 `main.py` 的 `ServerConfig` 类中或通过环境变量配置，需要保证客户端与服务端一致。
 
-## 配置选项
+**Q: 匿名模式是什么？**
+A: 匿名模式使用临时 token，避免对话历史共享，保护隐私。
 
-| 配置项 | 描述 | 默认值 |
-|--------|------|--------|
-| `API_ENDPOINT` | Z.ai 的上游 API 地址 | `https://chat.z.ai/api/chat/completions` |
-| `AUTH_TOKEN` | 下游客户端鉴权 key | `sk-your-api-key` |
-| `BACKUP_TOKEN` | 上游 API 的 token (匿名模式失败时使用) | JWT token |
-| `PRIMARY_MODEL` | 默认模型名称 | `GLM-4.5` |
-| `THINKING_MODEL` | 思考模型名称 | `GLM-4.5-Thinking` |
-| `SEARCH_MODEL` | 搜索模型名称 | `GLM-4.5-Search` |
-| `LISTEN_PORT` | 服务监听端口 | `8080` |
-| `DEBUG_LOGGING` | 调试模式开关 | `true` |
-| `THINKING_PROCESSING` | 思考内容处理策略 | `think` (可选: `strip`, `raw`) |
-| `ANONYMOUS_MODE` | 是否使用匿名 token | `true` |
-| `TOOL_SUPPORT` | 是否启用 Function Call 功能 | `true` |
+**Q: Function Call 如何工作？**
+A: 通过智能提示注入实现，将工具定义转换为系统提示。
 
-### 思考内容处理策略说明
+**Q: 支持哪些 OpenAI 功能？**
+A: 支持聊天完成、模型列表、流式响应、工具调用等核心功能。
 
-- **think**: 将 `<details>` 标签转换为 `<thinking>` 标签，适合 OpenAI 兼容格式
-- **strip**: 完全移除 `<details>` 标签及其内容
-- **raw**: 保留原始格式，不做任何处理
+**Q: 如何自定义配置？**
+A: 通过环境变量或修改 `main.py` 中的 `ServerConfig` 类。
 
-## 架构说明
+## 🏗️ 技术架构
+
+```
+┌─────────────┐     ┌─────────────┐     ┌─────────────┐
+│  OpenAI     │     │   Proxy     │     │    Z.AI     │
+│  Client     │────▶│   Server    │────▶│    API      │
+│             │     │             │     │             │
+└─────────────┘     └─────────────┘     └─────────────┘
+```
 
-本项目采用以下技术栈：
+- **FastAPI** - 高性能 Web 框架
+- **Pydantic** - 数据验证和序列化
+- **Uvicorn** - ASGI 服务器
+- **Requests** - HTTP 客户端
 
-- **FastAPI**: 现代、快速的 Web 框架，提供自动 API 文档生成
-- **Pydantic**: 数据验证和序列化，确保 API 兼容性
-- **uvicorn**: ASGI 服务器，提供高性能服务
+## 🤝 贡献指南
 
-项目通过异步编程模型实现高效的并发处理，支持流式和非流式两种响应模式。
+我们欢迎所有形式的贡献！
+请确保代码符合 PEP 8 规范，并更新相关文档。
 
-## 贡献指南
+## 📄 许可证
 
-欢迎提交 Issue 和 Pull Request！请确保：
-1. 遵循 PEP 8 规范
-2. 提交前运行测试（如果有）
-3. 更新相关文档
+本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。
 
-## 许可证
+## ⚠️ 免责声明
 
-MIT LICENSE
+- 本项目与 Z.AI 官方无关
+- 使用前请确保遵守 Z.AI 服务条款
+- 请勿用于商业用途或违反使用条款的场景
+- 项目仅供学习和研究使用
 
-## 免责声明
+---
 
-本项目与 Z.ai 官方无关，使用前请确保遵守 Z.ai 的服务条款。请勿将此服务用于商业用途或违反 Z.ai 使用条款的场景。
+<div align="center">
+Made with ❤️ by the community
+</div>