qwen2API Enterprise Gateway

语言 / Language: 中文 | English

将通义千问（chat.qwen.ai）网页版 Web 对话能力转换为 OpenAI、Claude 与 Gemini 兼容 API。后端为 Python (FastAPI) 全量实现，不依赖其他运行时；前端为基于 React + Shadcn 构建的管理台，提供现代化的 Slate/Indigo 暗黑主题交互面板。

---

架构概览

qwen2API 2.x（企业级模块化版）

flowchart LR
    Client["🖥️ 客户端 / SDK\n(OpenAI / Claude / Gemini)"]
    Upstream["☁️ 通义千问 Web API\n(chat.qwen.ai)"]

    subgraph qwen2API["qwen2API Enterprise Gateway"]
        Router["FastAPI Router\n(CORS / Auth / 流式响应)"]

        subgraph Adapters["协议适配层"]
            OA["OpenAI 兼容接口\n/v1/chat/completions"]
            CA["Claude 兼容接口\n/anthropic/v1/messages"]
            GA["Gemini 兼容接口\n/v1beta/models/*"]
            Admin["Admin API\n/api/admin/*"]
            WebUI["Admin Dashboard\n(React + Shadcn)"]
        end

        subgraph Runtime["运行时核心能力"]
            Engine["Browser Engine\n(Camoufox 无头浏览器)"]
            Pool["Account Pool + Queue\n(并发锁与排队缓冲)"]
            Auth["Auth Resolver\n(无头模拟登录/凭证自愈)"]
            ClientCore["Qwen Client\n(SSE 流解析与重试机制)"]
            Tool["Tool Sieve\n(##TOOL_CALL## 拦截与解析)"]
            TokenCalc["Token Calculator\n(Tiktoken 精准计费)"]
            GC["Garbage Collector\n(15分钟定时清理孤儿会话)"]
            DB["Async JSON DB\n(带锁持久化)"]
        end
    end

    Client --> Router
    Router --> OA & CA & GA
    Router --> Admin
    Router --> WebUI

    OA & CA & GA --> Tool
    Tool --> ClientCore
    ClientCore -.无感重试.-> Pool
    ClientCore -.精确计费.-> TokenCalc
    ClientCore --> Engine

    Auth -.失效自愈.-> Pool
    GC -.定时清理.-> Engine

    Admin --> DB
    Admin --> Pool

    Engine --> Upstream
    Upstream --> Engine

Loading

• 后端：Python (FastAPI + Uvicorn + Camoufox 无头引擎)
• 前端：React + Vite 6 + Shadcn UI 管理台
• 部署：支持本地脚本启动、Docker 容器化部署、Zeabur 一键托管、Vercel 代理等方案

核心特性与架构升级

• 全协议原生适配：原生提供对 OpenAI (/v1/*)、Anthropic (/anthropic/v1/messages) 与 Gemini (/v1beta/models/*) 接口的深度转换。
• Tool Calling (工具调用) 与 CoT 记忆链：针对千问网页版缺乏原生 Function Calling 的缺陷，植入底层的 Prompt 劫持与流式文本剥离机制。完美支持 OpenAI SSE 流式规范（严格遵循 role -> tool_calls -> finish 组装顺序），并在历史上下文中自动持久化模型的思考过程（Reasoning Text），完美兼容 OpenClaw、Claude Code 等高阶 Agent 框架的多轮复杂调度。
• JSON 异常自愈网络：内置强制纠错回调。当大模型在长文本中输出非法的 JSON 结构（如未转义的换行符或引号）时，解析层会拦截异常并向外抛出带有修正提示的伪造 Tool Call，利用外部客户端的自动重试机制逼迫模型自愈。
• 无感容灾重拨与账号轮询：当某个上游账号被限流（Rate Limit）或发生 Token 异常时，底层拦截器会挂起当前请求，并自动从并发池中抓取健康账号重试，全程对下游 SDK 透明。
• Aliyun WAF 绕过与凭证自愈引擎：探针层引入真实浏览器指纹与 Header 伪装，完美绕过阿里云 WAF 的静态请求拦截。当遇到账号被封禁、待激活或凭证过期（HTTP 401/403）时，系统会自动在后台调度无头浏览器执行自动邮件读取、点击激活链接及重新提取 Token 的全量自动化自愈闭环。
• 冷酷的精算师 (Token Calculator)：深度内嵌 tiktoken 算法引擎，精准计算每个请求的 Token 消耗，确保多租户额度扣减的绝对准确。

---

核心能力与接口支持

能力类型	接口/路径支持	详细说明
OpenAI 兼容	GET /v1/models、POST /v1/chat/completions、POST /v1/embeddings	完整支持 Stream 响应与函数调用；Embeddings 使用伪 Hash 模拟。
Claude 兼容	POST /anthropic/v1/messages	原生兼容 Anthropic SDK，处理复杂的 Block 结构与系统级 Prompt。
Gemini 兼容	POST /v1beta/models/{model}:generateContent、...:streamGenerateContent	拦截 Google AI SDK 的专有协议体并平滑转换至底层。
多账号并发轮询	-	自动 Token 刷新，支持手机号/邮箱/临时验证码等多路径登录自愈，内建负载均衡器。
并发队列控制	-	为每个账号设定 In-flight 上限与排队槽位，防范封禁风险。
Tool Calling	-	完美对齐 OpenAI 流式标准；支持带思考过程的工具调度；支持非法 JSON 自我纠错机制。
Admin API	/api/admin/*	提供动态配置更新、账号管理批量测试、清理上游会话、统计看板拉取等接口。
WebUI 管理台	/ (前端静态托管)	现代化暗黑主题（Slate/Indigo）一站式 React 单页应用，提供直观的 Token 获取教程及账号运维控制台。
运维探针	/healthz、/readyz	用于 Docker / K8s 的健康检测，确保服务状态随时可达。

---

平台与客户端兼容矩阵

兼容级别	平台 / 客户端 / SDK	当前状态	备注
P0	OpenAI 官方 SDK (Node.js / Python)	✅ 完美兼容	涵盖 Chat 与 Stream。
P0	Anthropic 官方 SDK	✅ 完美兼容	支持多模态（文本）。
P0	Google Gemini SDK	✅ 完美兼容	支持 GenerateContent 流。
P0	Vercel AI SDK	✅ 完美兼容	原生适配 openai-compatible。
P0	Claude Code / OpenClaw	✅ 完美兼容	深度支持系统级文件读写、工具链反馈环及多轮 CoT 记忆。
P1	OpenWebUI / NextChat	✅ 完美兼容	无缝接入，支持对话隔离。
P1	LangChain / LlamaIndex	✅ 完美兼容	针对复杂的 Agent 工具链表现优异。

---

智能模型路由

为保证各客户端的最佳生成效果，系统内部实现了智能模型名称映射路由，自动将各类通用模型名锚定到通义千问的最优模型：

客户端请求传入的模型名 (Alias)	实际调用的底层目标模型
gpt-4o / gpt-4-turbo / o1 / o3	qwen3.6-plus
gpt-4o-mini / gpt-3.5-turbo / o1-mini	qwen3.5-flash
claude-3-5-sonnet / claude-opus-4-6	qwen3.6-plus
claude-3-haiku / claude-3-5-haiku-latest	qwen3.5-flash
gemini-2.5-pro / gemini-1.5-pro	qwen3.6-plus
deepseek-chat / deepseek-reasoner	qwen3.6-plus

提示：如果未命中上述映射表，系统默认将 fallback 回落到 qwen3.6-plus。

---

快速开始

方式一：本地运行

前置环境要求：

• Python 3.10+
• Node.js 20.10.0+ (适配最新的 Vite 6 构建环境)

# 1. 克隆仓库
git clone https://github.com/YuJunZhiXue/qwen2API.git
cd qwen2API

# 2. 安装后端核心依赖
cd backend
pip install -r requirements.txt
python -m camoufox fetch  # 必须执行：下载无头浏览器内核

# 3. 安装并构建前端界面
cd ../frontend
npm install
npm run build  # 编译后的静态资源会自动放入后端服务目录

# 4. 退回根目录，启动服务
cd ..
python start.py

启动后：

• WebUI 控制台：通过 http://localhost:8080 访问。
• API 网关地址：默认绑定 http://localhost:8080。

方式二：Docker / Docker Compose (推荐)

项目内置了多阶段构建 Dockerfile，保障环境一致性。

# 1. 克隆仓库
git clone https://github.com/YuJunZhiXue/qwen2API.git
cd qwen2API

# 2. 启动服务编排
docker-compose up -d

# 3. 实时查看日志
docker-compose logs -f

启动完成后，默认会将容器的 8080 端口映射至宿主机。通过 http://localhost:8080 即可进入控制台。更新镜像可执行 docker-compose up -d --build。

方式三：Zeabur 一键部署

1. 点击页面顶部的 Deploy on Zeabur 徽章按钮，开启托管流程。
2. 部署完成后，访问生成的域名进入管理台。
3. 默认需配置环境变量 ADMIN_KEY 作为后台登录鉴权。

方式四：Vercel 代理部署

1. Fork 仓库至个人 GitHub。
2. 在 Vercel 工作台导入项目。
3. 配置必要环境变量（注：由于 Serverless 架构限制，无法内部长驻无头浏览器，此方案通常作为代理层接入外部独立部署的无头节点）。
4. 部署并绑定域名。

---

全局配置与数据持久化

核心运行时数据默认存储于 data/ 目录（首次启动时自动生成，使用 Docker 部署时建议通过 Volume 挂载以防数据丢失）：

• data/accounts.json：存放上游千问账号矩阵、Token 凭证及并发控制状态。
• data/users.json：存放签发给下游调用的 API Key 及额度统计记录。
• data/config.json (可选)：高级运行时参数配置。

安全提示：请妥善保管 data/ 目录，避免核心凭证与计费数据泄露。

---

许可证与免责声明

本项目采用 MIT License 许可开源。

免责声明（重要）： 本项目仅供个人学习与自动化技术研究使用，旨在探讨浏览器自动化与 API 协议转换的技术实现。

1. 本项目与相关官方服务（如阿里云、通义千问等）无任何利益关联，绝非官方提供的商业接口。
2. 严禁将本项目用于任何非法商业牟利、高并发灰黑产、或违反通义千问官方用户协议的生产环境中。
3. 因滥用本项目代码导致的一切账号封禁、数据泄露或法律纠纷，由使用者自行承担全部责任，项目及开发者概不负责。
4. 若本项目的存在无意间侵犯了相关权利方的合法权益，请提交 Issue，我们将积极配合处理。