gpt4free：聚合多家模型接口的 Python 调用库

想调用 GPT、Gemini、DeepSeek 这类模型，常规路径有两条：买官方 API 额度，或者自己准备显卡把权重跑起来。gpt4free 走的是第三条路，它把多家平台公开的网页端接口逆向出来，统一包装成一套调用入口，用户不用 API key 也能拿到模型输出。

gpt4free 是用 Python 写的多提供方模型聚合调用库，把多家网页端模型封装成统一的 Python 客户端、OpenAI 兼容 API 和本地 Web 界面，输入提示词取回文本或生成的媒体文件。

仓库的 Topics 里同时挂着 chatbot、reverse-engineering、openai-api 这些标签，指向它真实的用法：把请求转发到不同的 provider 上，当 OpenAI 接口的替代层用。项目由 @xtekky 创建、@hlohaus 维护，采用 GPL-3.0 许可证，主要语言 Python 占 90.2%，其余是 JavaScript、HTML、Go、CSS 和 Java。仓库地址是 https://github.com/xtekky/gpt4free，目前有 66738 个 Star、13496 个 Fork、489 个 Watcher，开放 Issue 5 个。

基础用法

安装与依赖

README 把 Docker 列为推荐方式，完整镜像的拉取与启动命令是：

docker pull hlohaus789/g4f

docker run -p 8080:8080 -p 7900:7900 \
  --shm-size="2g" \
  -v ${PWD}/har_and_cookies:/app/har_and_cookies \
  -v ${PWD}/generated_media:/app/generated_media \
  hlohaus789/g4f:latest

8080 端口提供 GUI 与 API，7900 端口可选地暴露一个类 VNC 桌面，用来登录需要账号的 provider。浏览器自动化任务较重时，README 建议把 --shm-size 调大。

slim 镜像同时支持 x64 与 arm64，端口映射方式不同：

mkdir -p ${PWD}/har_and_cookies ${PWD}/generated_media
chown -R 1000:1000 ${PWD}/har_and_cookies ${PWD}/generated_media

docker run \
  -p 1337:8080 -p 8080:8080 \
  -v ${PWD}/har_and_cookies:/app/har_and_cookies \
  -v ${PWD}/generated_media:/app/generated_media \
  hlohaus789/g4f:latest-slim

slim 镜像会在启动时更新 g4f 包，并按需补装依赖。

Python 侧要求 3.10 及以上，部分 provider 需要本机装有 Chrome/Chromium。从 PyPI 安装：

pip install -U g4f[all]

从源码安装：

git clone https://github.com/xtekky/gpt4free.git
cd gpt4free
pip install -r requirements.txt
pip install -e .

顶层放了三份依赖清单，requirements.txt、requirements-slim.txt、requirements-min.txt，分别对应完整、精简、最小三种安装。Windows 用户可以从 Release 下载 g4f.exe.zip，解压后运行 g4f.exe，界面同样在 http://localhost:8080/chat/。

最短能跑通的示例

启动本地服务的命令是：

python -m g4f --port 8080 --debug

打开 http://localhost:8080/chat/ 就是 Web 客户端。只启 GUI 可以换 CLI 子命令：

python -m g4f.cli gui --port 8080 --debug

Python 客户端的用法在 README 的 Using the Python client 一节，分同步文本、图像生成、异步三组示例。事实表给出的 README 节选没有展开这三段代码，具体写法要看仓库对应章节。

确认它跑起来了

加 --debug 后终端会打印监听端口和 provider 的加载情况。浏览器访问 http://localhost:8080/chat/ 能看到对话界面，GUI 服务就是正常的。

用 slim 镜像时，Interference API 映射在 1337 端口，OpenAI 兼容入口是 http://localhost:1337/v1，Swagger UI 在 http://localhost:1337/docs。生成的图片、音频等媒体文件落在挂载出来的 generated_media 目录，provider 登录用的 .har 文件与 cookie 放在 har_and_cookies 目录。这两个目录没有挂载出来，重启容器后内容会丢。

主要功能

模型接入与客户端

• 多提供方适配：内置 LLM、媒体提供方和本地推理后端三类适配器，调用时切换目标 provider。可用性取决于对方的网页接口，接口一变这个 provider 就失效。
• 客户端库：Python 侧提供同步与异步两套客户端，接口形状与 OpenAI 一致，chat.completions.create 这类调用可以直接沿用。另有官方浏览器 JS 客户端 GPT4Free.js，通过 g4f.dev 分发。
• MCP Server：README 提到项目现在包含一个 Model Context Protocol 服务，供 AI 助手类工具调用。事实表里的 README 节选在这里截断，没有给出启动参数与配置说明。

本地服务、界面与媒体生成

• 本地 Web GUI：通过 g4f.gui 模块的 run_gui() 或 CLI 的 gui 子命令启动，默认页面在 /chat/。它是单机界面，不带多用户权限体系。
• Interference API：基于 FastAPI 的 OpenAI 兼容接口，python -m g4f --port 8080 启动。任何能配置 base_url 的 OpenAI 客户端都能指向它，用来替换官方端点。
• CLI：python -m g4f.cli 提供命令行入口，例如 gui 子命令，带 --port 与 --debug 两个参数。
• 媒体生成与持久化：图像、音频、视频生成的结果会写入 generated_media，仓库顶层也保留了同名目录。
• Docker 与可执行文件：完整镜像和 slim 镜像都在 Docker Hub 的 hlohaus789/g4f 下。从 v8.5.8 起的 Release 还带 g4f-go 打包的可执行文件，分 Windows amd64 与 Linux x64 两个平台，内置嵌入式 Python，不装 Python 环境也能跑。

参数与配置

常用参数

• --port：指定服务监听端口，README 示例用 8080。
• --debug：打开调试输出，排查 provider 加载失败时用。
• --shm-size：Docker 运行参数，浏览器自动化任务重时调大。
• -p 7900:7900：把容器里的类 VNC 桌面映射出来，用于登录需要账号的 provider。

provider 的指定方式在 README 的 Providers & models 概览章节里，事实表给出的节选没有展开具体参数名。Grok 这类 provider 会拉起 nodriver 浏览器进程，也是 Issue 里报错集中的地方。

配置文件

仓库顶层放了 example.env，从文件名看是环境变量的样例文件，事实表没有列出里面有哪些字段，README 节选里也没有对应的字段说明。Docker 部署另有两份 compose 文件，docker-compose.yml 与 docker-compose-slim.yml。

需要维持登录态的 provider，认证信息以 .har 文件和 cookie 的形式存放在 har_and_cookies 目录，容器部署时必须通过 -v 把它挂载出来。

实际使用中的坑

• OpenaiChat 报 MissingAuthError，提示需要补 api_key 或 .har 文件。这是该 provider 改用 .har 认证后的典型报错，讨论量在 Issue 列表里靠前，已关闭。
• .har 认证返回 401，错误信息是 token_expired，要求重新登录。同类问题还有 ChatGPT provider 读不到 .har 文件、.har 文件里找不到 arkose token。这三种都属于登录态过期或抓取不完整，要在容器里重新登录并替换 .har 文件，对应的 Issue 均已关闭。
• Grok provider 反复弹出 nodriver 窗口，并刷 ERROR:g4f.api:list index out of range。出在浏览器自动化路径上，Issue 已关闭。
• 在 iSH 这类 x86 模拟环境里 pip 安装 curl_cffi 会遇到 Unsupported arch。已关闭。
• 社区讨论过 takedown，有人建议直接做成 Docker 镜像自行托管，降低单点下架的影响。该 Issue 已关闭。

这些 Issue 的状态都是已解决，但解决的是当时那一刻的报错。provider 依赖的是别人的网页接口，接口一改，同类问题会以新的形式回来。

同类项目对比

要把某个模型稳定地跑在生产环境，gpt4free 不适合：它依赖各家网页接口，provider 会失效，认证方式会变，仓库本身出现过下架讨论。这类需求更适合走 vLLM 那种能自己掌控权重的推理服务方向，或者直接买官方 API。反过来，只在本地做原型验证、想横向比较几家模型的输出，gpt4free 的安装成本和切换成本都很低。Gepetto 只解决 IDA 里读反汇编这一件事，和本项目的适用范围没有交叠，列在这里只是给同类选型的读者一个参照。

合规边界

gpt4free 的 provider 大量来自对第三方平台网页接口的逆向，部分还需要注入 .har 文件或 cookie 维持登录态。这类做法处在平台服务条款的灰区，官方仓库自己也出现过下架讨论，并单独提供了 LEGAL_NOTICE.md。

把它用在自有账号、自建环境上做验证，风险由使用者自己承担。拿它去绕过付费限制、批量抓取他人服务，或者对外提供商业调用，可能同时踩到平台条款与法律问题。GPL-3.0 还要求分发修改版时按同样条款开源。

适合谁

适合手上没有 API key、又想横向试几家模型的个人开发者。适合需要在本机跑一个 OpenAI 兼容端点、把现有工具指过来的调试场景。也适合想研究逆向接口怎么封装的读者，仓库里 provider 适配器的写法可以直接读。

不适合把可用性写进 SLA 的生产系统，provider 可能失效，认证方式可能变，仓库里没有稳定性承诺。真要跑线上业务，官方 API 或者能自己掌控权重的自建推理更合适。完全不想碰命令行和 Docker 的人也不适合。

焚评：这个项目的量化评分

本项目的选题来自 焚.com（一个按公开公式给 GitHub 项目打分的站）。焚评当前总分 10.0 分（满分 10）。下表是各维度的得分：

评分口径、权重与计算方式见焚.com 的评分方法页；数据随 GitHub 指标刷新，具体数值以焚.com 当前页面为准。本文正文为诀.com 独立撰写，评分数据由焚.com 授权引用。