Skip to content

sevenokey/z.ai2api_python

BranchesTags
 
 

Repository files navigation

OpenAI 代理服务

License: MIT Python: 3.9-3.12 FastAPI

基于 FastAPI 的高性能 OpenAI API 兼容代理服务，采用多提供商架构设计，支持 Z.AI（GLM-4.5/4.6 系列）、K2Think、LongCat 等多种 AI 模型。

✨ 核心特性

  • 🔌 OpenAI API 兼容 - 无缝对接现有 OpenAI 客户端
  • 🏗️ 多提供商架构 - 统一接口支持 Z.AI、K2Think、LongCat
  • 🧬 数据库管理 - SQLite + Web 后台统一管理 Token
  • 🚀 流式响应 - 高性能 SSE 实时流式输出
  • 🧠 思考模式 - 支持 Thinking 模型的推理过程展示
  • 🐳 容器化部署 - Docker/Docker Compose 一键部署
  • 🔄 Token 池 - 智能轮询、容错恢复、健康检查
  • 📊 管理后台 - 实时监控、配置管理
  • 🔐 安全认证 - 密码保护的管理后台访问

❤️ 感谢各位的反馈推动项目改进！

🚀 快速开始

环境要求

  • Python 3.9-3.12
  • pip 或 uv (推荐)

本地运行

# 1. 克隆项目
git clone https://github.com/ZyphrZero/z.ai2api_python.git
cd z.ai2api_python

# 2. 安装依赖（使用 uv 推荐）
curl -LsSf https://astral.sh/uv/install.sh | sh
uv sync

# 或使用 pip
pip install -r requirements.txt

# 3. 配置环境变量
cp .env.example .env
# 编辑 .env 文件，设置 AUTH_TOKEN 等配置

# 4. 启动服务
uv run python main.py  # 或 python main.py

首次运行会自动初始化数据库，访问以下地址：

⚠️ 重要：

  • 请妥善保管 AUTH_TOKEN，不要泄露给他人
  • 管理后台默认密码为 admin123，首次使用后请立即修改

Docker 部署

从 Docker Hub 拉取镜像：

# 拉取最新镜像
docker pull zyphrzero/z-ai2api-python:latest

# 快速启动（创建数据目录）
mkdir -p data logs

# 运行容器
docker run -d \
  --name z-ai-api-server \
  -p 8080:8080 \
  -e ADMIN_PASSWORD=admin123 \
  -e AUTH_TOKEN=sk-your-api-key \
  -e ANONYMOUS_MODE=true \
  -e DB_PATH=/app/data/tokens.db \
  -v $(pwd)/data:/app/data \
  -v $(pwd)/logs:/app/logs \
  --restart unless-stopped \
  zyphrzero/z-ai2api-python:latest

启动服务：

docker compose up -d

方式二：本地构建

# 进入部署目录
cd deploy

# 启动服务（会自动构建镜像）
docker compose up -d

# 查看日志
docker compose logs -f api-server

数据持久化

容器使用卷映射自动持久化数据：

data/                  # 数据库文件存储目录
├── tokens.db          # SQLite 数据库（自动创建）
logs/                  # 日志文件存储目录

数据在容器重启或重建后仍然保留，无需担心丢失。

📖 详细文档：Docker 部署指南

📖 支持的模型

Z.AI 提供商（GLM 系列）

模型 上游 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 多模态模型，支持图像理解
GLM-4.6 GLM-4-6-API-V1 新版标准模型，200K 上下文
GLM-4.6-Thinking GLM-4-6-API-V1 新版思考模型，增强推理
GLM-4.6-Search GLM-4-6-API-V1 新版搜索模型，改进联网能力
GLM-4.6-advanced-search GLM-4-6-API-V1 高级搜索模型，深度研究

K2Think 提供商

模型 特性
MBZUAI-IFM/K2-Think 高质量推理模型

LongCat 提供商

模型 特性
LongCat-Flash 快速响应
LongCat 标准模型
LongCat-Search 搜索增强

⚙️ 配置说明

核心环境变量

变量名 默认值 说明
AUTH_TOKEN sk-your-api-key 客户端访问密钥（必填）
ADMIN_PASSWORD admin123 管理后台登录密码（强烈建议修改）
LISTEN_PORT 8080 服务监听端口
DEBUG_LOGGING false 调试日志（支持热重载）
ANONYMOUS_MODE true Z.AI 匿名模式
TOOL_SUPPORT true Function Call 开关
SKIP_AUTH_TOKEN false 跳过认证（仅开发）
DB_PATH tokens.db 数据库文件路径（Docker: /app/data/tokens.db）

Token 配置

变量名 说明
LONGCAT_TOKEN LongCat 认证 Token（可选）
TOKEN_FAILURE_THRESHOLD Token 失败阈值（默认 3）
TOKEN_RECOVERY_TIMEOUT Token 恢复超时（默认 1800 秒）

💡 详细配置请参考 .env.example 或 deploy/.env.example

🔐 管理后台登录

首次登录

  1. 启动服务后访问：http://localhost:8080/admin
  2. 自动跳转到登录页面
  3. 输入管理密码（默认：admin123）
  4. 登录成功后进入仪表盘

修改密码

在 .env 文件中修改 ADMIN_PASSWORD：

# 使用强密码（推荐 12 位以上）
ADMIN_PASSWORD=Your_Secure_Password_2025!

重启服务后生效。

安全特性

  • ✅ Session 管理：基于 Cookie 的安全 Session
  • ✅ 自动过期：登录后 24 小时自动失效
  • ✅ HttpOnly Cookie：防止 XSS 攻击
  • ✅ SameSite 保护：防止 CSRF 攻击
  • ✅ 随机 Token：使用加密安全的随机数生成

💡 详细文档：管理后台登录功能使用说明

🔄 Token 管理

数据库方式（推荐）

项目使用 SQLite 数据库统一管理 Token，首次运行会自动初始化：

# 首次运行自动创建 tokens.db
python main.py

# 访问 Web 管理后台
http://localhost:8080/admin

管理后台功能

  • ✅ 密码保护 - 安全的登录认证
  • ✅ Token 增删改查
  • ✅ 批量导入/导出
  • ✅ 启用/禁用 Token
  • ✅ Token 有效性检测
  • ✅ 多提供商支持（Z.AI/K2Think/LongCat）

Token 池机制

  • 负载均衡：轮询使用多个 Token 分散请求
  • 自动容错：Token 失败时自动切换
  • 自动恢复：失败 Token 超时后重试
  • 智能去重：自动检测重复 Token
  • 回退机制：认证失败自动降级匿名模式

❓ 常见问题

Q: 如何获取 AUTH_TOKEN？

A: AUTH_TOKEN 是自定义的 API 密钥，用于客户端访问本服务，需在 .env 文件或 docker-compose.yml 中配置，确保客户端与服务端一致。

Q: 匿名模式是什么？

A: 匿名模式使用临时 Token 访问 Z.AI，避免对话历史共享，保护隐私。设置 ANONYMOUS_MODE=true 启用。

Q: 如何管理 Token？

A: 访问 Web 管理后台 http://localhost:8080/admin/tokens（需要先登录）即可增删改查 Token，支持批量导入导出。

Q: 忘记管理后台密码怎么办？

A: 在 .env 文件或 docker-compose.yml 中修改 ADMIN_PASSWORD 为新密码，然后重启服务即可。

Q: Docker 部署时数据库初始化失败？

A: 错误提示 unable to open database file 通常是权限问题。解决方案：

cd deploy
mkdir -p ./data ./logs
chmod 755 ./data ./logs
docker compose down && docker compose up -d --build

详见 Docker 部署指南

Q: 如何禁用管理后台登录？

A: 当前版本暂不支持禁用登录功能。如有需要，请手动移除路由中的 dependencies=[Depends(require_auth)]。

🔑 获取 Token

Z.AI Token

  1. 访问 Z.AI 官网 并登录
  2. 按 F12 打开开发者工具
  3. 进入 Application → Local Storage → Cookies
  4. 复制 token 值

⚠️ 多模态功能需要非匿名 Token

LongCat Token

  1. 访问 LongCat 官网 并登录美团账号
  2. 按 F12 打开开发者工具
  3. 进入 "Application" -> "Local Storage" -> "Cookie"列表中找到名为passport_token_key的值
  4. 复制 passport_token_key 值

🛠️ 技术栈

组件 技术 版本 说明
Web 框架 FastAPI 0.116.1 高性能异步框架
ASGI 服务器 Granian 2.5.2 Rust 高性能服务器
HTTP 客户端 HTTPX 0.28.1 异步 HTTP 客户端
数据验证 Pydantic 2.11.7 类型安全验证
数据库 SQLite (aiosqlite) 0.20.0 Token 存储
模板引擎 Jinja2 3.1.4 Web 后台模板
日志系统 Loguru 0.7.3 结构化日志

🏗️ 系统架构

┌─────────────┐      ┌────────────────────────────────┐      ┌──────────────┐
│   OpenAI    │      │      FastAPI Server            │      │   Z.AI API   │
│   Client    │─────▶│                                │─────▶│   (GLM-4.x)  │
└─────────────┘      │  ┌──────────────────────────┐  │      └──────────────┘
                     │  │   Provider Router        │  │
                     │  │  ┌────────┬────────────┐ │  │      ┌──────────────┐
                     │  │  │ Z.AI   │ K2Think    │ │  │      │  K2Think API │
                     │  │  │Provider│ Provider   │ │  │─────▶│              │
                     │  │  └────────┴────────────┘ │  │      └──────────────┘
                     │  │  ┌────────────┐          │  │
                     │  │  │ LongCat    │          │  │      ┌──────────────┐
                     │  │  │ Provider   │          │  │      │ LongCat API  │
                     │  │  └────────────┘          │  │─────▶│              │
                     │  └──────────────────────────┘  │      └──────────────┘
                     │                                │
                     │  ┌──────────────────────────┐  │
                     │  │   Web Admin Dashboard    │  │
                     │  │   (Token/Stats/Monitor)  │  │
                     │  └──────────────────────────┘  │
                     └────────────────────────────────┘
                               ↕
                          ┌─────────┐
                          │SQLite DB│
                          │(tokens) │
                          └─────────┘

🤝 贡献指南

欢迎提交 Issue 和 Pull Request！请确保代码符合 PEP 8 规范。

⭐ Star History

Star History Chart

📄 许可证

本项目采用 MIT 许可证 - 详见 LICENSE 文件。

⚠️ 免责声明

  • 本项目与 Z.AI、K2Think、LongCat 等 AI 提供商官方无关
  • 使用前请确保遵守各提供商的服务条款
  • 请勿用于商业用途或违反使用条款的场景
  • 项目仅供学习和研究使用
  • 用户需自行承担使用风险
Made with ❤️ by the community

About

支持 Z.AI、K2Think、LongCat 等多个 AI 提供商的高性能代理服务

Resources

Readme

License

MIT license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages

  • Python 72.5%
  • HTML 27.4%
  • Dockerfile 0.1%