首页
/ GPT4Free (g4f) 完全实践指南：多提供商聚合、Python/JS 客户端、Docker 部署与 Interference API

GPT4Free (g4f) 完全实践指南：多提供商聚合、Python/JS 客户端、Docker 部署与 Interference API

2026-09-04 23:30:55作者：卓炯娓
gpt4free
The official gpt4free repository | various collection of powerful language models | opus 4.6 gpt 5.3 kimi 2.5 deepseek v3.2 gemini 3
项目地址：https://gitcode.com/GitHub_Trending/gp/gpt4free

本文以 GPT4Free（g4f）官方 README 为主体，系统讲解这个多 LLM 提供商聚合框架的安装部署（Docker / 精简镜像 / pip / 源码）、三种运行形态（Web GUI、OpenAI 兼容 API、MCP 服务器）、Python 同步/异步客户端的完整用法，以及如何通过环境变量与 config.yaml 进行模型路由定制；结合仓库源码可进一步印证客户端的提供商回退逻辑与配置加载机制，帮助你把一个「一个入口、多家模型」的 LLM 服务真正跑起来。

g4f Docker 容器背景图

一、项目定位：它包含什么

GPT4Free 是一个社区驱动的聚合项目：它将多个可访问的 LLM 与媒体生成提供商统一在一套接口之后，让用户不必关心底层是哪家 API。根据 README 的 "What's included" 部分，项目交付物包括：

  • Python 客户端库（Client 同步客户端与 AsyncClient 异步客户端）；
  • 可选的本地 Web GUI（/chat/ 页面）；
  • 基于 FastAPI 的 OpenAI 兼容 REST API（项目称为 Interference API）；
  • 官方浏览器 JS 客户端（通过 g4f.dev 分发）；
  • Docker 完整镜像与精简（slim）镜像；
  • 多提供商适配器（LLM、媒体生成、本地推理后端）；
  • 图像/音频/视频生成工具链与媒体持久化能力。

从源码结构看，g4f/Provider/ 目录下按类别组织了大量提供商适配器：audio/（EdgeTTS、ElevenLabs 等）、local/（Local、Ollama）、needs_auth/（Anthropic、Cohere、DeepSeek、Gemini 等需密钥或登录的提供商）、hf_space/（HuggingFace Space 上的 Flux、SD3.5 等图像模型）、search/（DDGS、GoogleSearch、SearXNG 等搜索源）。每个适配器文件即一个 provider 实现，这是理解该项目所有功能的索引入口。

二、环境与兼容性要求

  • Python 3.10+（推荐）；
  • 使用浏览器自动化类提供商时需要 Google Chrome/Chromium；
  • 容器化部署需要 Docker；
  • 架构支持 x86_64 与 arm64（slim 镜像两者都支持，参见 docs/aarch64-compatibility.md）；
  • 部分提供商适配器需要平台级工具（Chrome/Chromium 等），具体以各提供商文档为准。

三、安装方式

3.1 Docker（推荐）

  1. 创建持久化目录并设置属主（容器内运行用户 UID/GID 为 1200:1201）：
mkdir -p ${PWD}/har_and_cookies ${PWD}/generated_media
sudo chown -R 1200:1201 ${PWD}/har_and_cookies ${PWD}/generated_media
  1. 拉取并启动镜像：
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 桌面，用于在容器内手动登录 Web 提供商以获取 cookie/HAR 文件；
  • --shm-size="2g" 是浏览器自动化任务的关键参数，负载更重时建议继续加大；
  • 两个卷的作用：har_and_cookies 持久化 HAR 与 cookie 文件，generated_media 持久化生成的媒体文件。

镜像构建细节可参考 docker/Dockerfile、docker/Dockerfile-slim、docker/Dockerfile-armv7 与启动脚本 docker/start.sh，服务进程由 supervisor 管理（docker/supervisor.conf、docker/supervisor-api.conf）。

3.2 Slim Docker 镜像（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 镜像的容器内用户是 1000:1000（完整镜像是 1200:1201）；本示例中把容器 8080 端口额外映射到了宿主 1337，即 Interference API 的对外入口为 http://localhost:1337/v1，Swagger UI 在 http://localhost:1337/docs。slim 镜像可在启动时更新 g4f 包并按需安装额外依赖。仓库根目录提供了现成的编排文件 docker-compose.yml 与 docker-compose-slim.yml 可直接参考。

3.3 Windows（.exe 启动器）

  1. 从项目 Releases 页面下载 g4f.exe.zip 并解压运行 g4f.exe（Windows 启动器另有独立仓库 g4f/g4f.exe）；
  2. 浏览器打开 http://localhost:8080/chat/ 即进入 GUI；
  3. 若 Windows 防火墙拦截，允许该应用通过即可。

3.4 Python 安装（pip / 源码 / 部分安装）

前置条件：Python 3.10+，部分提供商需要 Chrome/Chromium。

从 PyPI 安装（推荐）：

pip install -U g4f[all]

部分安装：[all] 会带入全部可选依赖。若只需特定功能，可使用 extras 组裁剪安装体积；依赖清单可对照仓库中的 requirements.txt、requirements-min.txt 与 requirements-slim.txt。

从源码安装：

git clone https://gitcode.com/GitHub_Trending/gp/gpt4free
cd gpt4free
pip install -r requirements.txt
pip install -e .

四、运行应用

4.1 GUI（Web 客户端）

两种方式等价：

from g4f.gui import run_gui
run_gui()

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

启动后访问 http://localhost:8080/chat/。实现入口位于 g4f/gui/run.py，服务端逻辑在 g4f/gui/server/（app.py、api.py、backend_api.py、website.py 等）。

4.2 FastAPI / Interference API

python -m g4f --port 8080 --debug

python -m g4f 会执行 g4f/main.py 中的 CLI 入口。在 slim Docker 映射方式下，API 通常位于 http://localhost:1337/v1，OpenAPI/Swagger UI 位于 http://localhost:1337/docs。API 主体实现在 g4f/api/run.py 与 g4f/api/init.py，它提供 OpenAI 风格的 chat/completions 等端点，由 GPT4Free 的提供商选择机制在幕后完成路由——即「OpenAI 式工作流 + 多提供商透明转发」。

4.3 CLI 与 MCP 服务器

MCP（Model Context Protocol）服务器让 Claude 等 AI 助手调用 Web 搜索、网页抓取与图像生成能力：

# stdio 模式
g4f mcp
# 或
python -m g4f.mcp

# HTTP 模式
g4f mcp --http --port 8765
g4f mcp --http --host 127.0.0.1 --port 3000

HTTP 模式提供两个端点：POST http://localhost:8765/mcp（JSON-RPC）与 GET http://localhost:8765/health（健康检查）。

配合 Claude Desktop，在 claude_desktop_config.json 中加入：

{
  "mcpServers": {
    "gpt4free": {
      "command": "python",
      "args": ["-m", "g4f.mcp"]
    }
  }
}

README 列出的 MCP 工具有：web_search（DuckDuckGo 搜索）、web_scrape（网页正文抽取）、image_generation（文生图）。仓库中附带了配置示例 g4f/mcp/claude_desktop_config.example.json，服务器实现见 g4f/mcp/server.py 与工具定义 g4f/mcp/tools.py。

4.4 容器内桌面登录（可选）

访问：

http://localhost:7900/?autoconnect=1&resize=scale&password=secret

该桌面用于登录 Web 版提供商，从而导出 cookie/HAR 文件供后续请求复用。

五、Python 客户端用法

pip install -U g4f[all]

5.1 同步文本请求

from g4f.client import Client

client = Client()
response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Hello, how are you?"}],
    web_search=False
)
print(response.choices[0].message.content)

预期输出类似 Hello! How can I assist you today?

5.2 图像生成

from g4f.client import Client

client = Client()
response = client.images.generate(
    model="flux",
    prompt="a white siamese cat",
    response_format="url"
)
print(f"Generated image URL: {response.data[0].url}")

5.3 异步客户端

from g4f.client import AsyncClient
import asyncio

async def main():
    client = AsyncClient()
    response = await client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": "Explain quantum computing briefly"}],
    )
    print(response.choices[0].message.content)

asyncio.run(main())

5.4 源码印证：提供商是如何被选择的

阅读 g4f/client/init.py 中 Completions.create 的实现（约 L355-L430），可以确认客户端的默认路由策略：

if provider is None:
    provider = self.provider
    if provider is None:
        from ..providers.any_provider import AnyProvider
        provider = AnyProvider

即：不指定 provider 时回落到客户端实例级提供商；仍为空则使用 AnyProvider，它从源码结构看是「遍历可用提供商直到成功」的聚合器（g4f/providers/any_provider.py）。create() 的关键参数还包括 stream、proxy、image/image_name（多模态输入，经 resolve_media 归一化为 media 列表）、response_format（json_object 时会对返回内容做 filter_json 清洗）、max_tokens、stop、ignore_stream、raw 等。

另一个值得注意的机制在 g4f/client/factory.py 的 create_custom_provider（L17-L64）：当 Client 构造时传入 base_url（或把 http(s) URL 作为 provider 参数），工厂会动态生成一个继承自 OpenaiTemplate 的自定义提供商类——

CustomProvider = type(name, (OpenaiTemplate,), class_attrs)

这意味着任何 OpenAI 兼容端点（含自建服务或第三方中转）都能零代码接入 g4f 客户端，base_url 成为第一公民参数。

图像生成侧，Images.async_generate 对 IterListProvider（提供商列表）会逐个尝试、失败即记日志继续下一个（约 L502-L533），最终无媒体响应时抛出 NoMediaResponseError；response_format 支持 url（返回原始 URL）、b64_json（抓取并转 base64）与默认值（下载并持久化到媒体目录，由 g4f/image/copy_images.py 的 copy_media 完成落盘）。

六、GPT4Free.js：浏览器端 JS 客户端

官方 JS 客户端可直接在浏览器中使用，无需自建后端：

<script type="module">
  import Client from 'https://g4f.dev/dist/js/client.js';

  const client = new Client();
  const result = await client.chat.completions.create({
      model: 'gpt-4.1',  // Or "gpt-4o", "deepseek-v3", etc.
      messages: [{ role: 'user', content: 'Explain quantum computing' }]
  });
  console.log(result.choices[0].message.content);
</script>

该客户端经 g4f.dev 的 CDN 分发；README 提醒需自行评估 CORS 与使用限制。

七、提供商与模型概览

GPT4Free 集成了大量提供商，包括但不限于 OpenAI 兼容端点、PerplexityLabs、Gemini、MetaAI、Pollinations（媒体）以及本地推理后端。模型可用性与行为取决于具体提供商能力。

各类型提供商的典型依赖：

依赖类型 适用提供商
API key / token needs_auth/ 下的密钥型提供商（Anthropic、Cohere、Groq、Nvidia 等）
浏览器 cookie / HAR 文件 通过浏览器自动化抓取的提供商（如 OpenaiAccount、Bing 系）
Chrome/Chromium 或无头浏览器 依赖浏览器自动化的提供商
本地模型二进制与运行时 本地推理后端（Local、Ollama）

密钥通过环境变量注入，参考 example.env：将文件重命名为 .env 并放入 cookie 目录，按需填写 G4F_API_KEY、OPENAI_API_KEY、GEMINI_API_KEY、DEEPINFRA_API_KEY、OPENROUTER_API_KEY 等变量。

八、配置与定制

8.1 全局配置：环境变量与目录约定

g4f/config.py 定义了核心默认值（L30-L45）：

DEFAULT_PORT = 1337
DEFAULT_TIMEOUT = 600
DEFAULT_STREAM_TIMEOUT = 120
DEFAULT_MODEL = "openai/gpt-oss-120b"

配置文件目录按平台解析：Linux 默认 ~/.config/g4f（若已存在 ~/.g4f 则优先），Windows 为 %APPDATA%/g4f，macOS 为 ~/Library/Application Support/g4f；cookie 目录为 <config_dir>/cookies，另有本地快捷目录 ./har_and_cookies（L36-L37）。

AppConfig.load_from_env 读取的环境变量包括：

环境变量 作用
G4F_API_KEY g4f 自定义 API 密钥
G4F_TIMEOUT 全局超时（默认 600 秒）
G4F_STREAM_TIMEOUT 流式超时（默认 120 秒）
G4F_PROXY 代理地址
G4F_MODEL / G4F_PROVIDER 默认模型 / 默认提供商
G4F_DISABLE_CUSTOM_API_KEY 禁用自定义 API key

8.2 config.yaml：自定义模型路由

g4f 支持把 config.yaml 放在 cookie 目录（与 .har/.json cookie 文件同目录，如 ~/.config/g4f/cookies/config.yaml 或 ./har_and_cookies/config.yaml），定义命名模型路由：客户端请求 name 中的模型名时，g4f 按序尝试 providers 列表中的提供商（满足 condition 者），直到成功。这一机制类似 LiteLLM 的路由配置，详见 docs/config-yaml-routing.md。

文件结构与键说明：

models:
  - name: "<model-name>"          # 客户端使用的名字
    providers:
      - provider: "<ProviderName>"  # g4f 提供商类名
        model: "<provider-model>"   # 转发给该提供商的模型名
        condition: "<expression>"   # 可选布尔表达式
      - provider: "..."             # 回退提供商（无 condition = 始终可选）
        model: "..."
键 必填 说明
name ✅ 客户端使用的模型名
providers ✅ 有序的提供商候选列表
provider ✅ 提供商类名，如 "OpenaiAccount"、"PollinationsAI"
model 转发给提供商的模型名，缺省取路由 name
condition 布尔表达式，控制该提供商是否可选

condition 可引用三类变量：

  • quota：提供商 get_quota() 返回的完整字典（内存缓存 5 分钟 TTL，收到 HTTP 429 时立即失效），支持点号访问嵌套字段，缺失键解析为 0.0。各提供商格式不同，例如 PollinationsAI 返回 {"balance": float}，Yupp 返回 {"credits": {"remaining": int, "total": int}}；
  • balance：quota.balance 的简写别名（为 PollinationsAI 兼容性保留）；
  • error_count：该提供商最近 1 小时内记录的错误数（超过 1 小时的错误自动清理）。

支持运算符 > < >= <= == != 与逻辑连接词 and or not、括号分组。完整示例见 etc/examples/config.yaml：

models:
  - name: "my-gpt4"
    providers:
      - provider: "OpenaiAccount"
        model: "gpt-4o"
        condition: "balance > 0 or error_count < 3"
      - provider: "PollinationsAI"
        model: "openai-large"

  - name: "llama-fast"
    providers:
      - provider: "Groq"
        model: "llama-3.3-70b"
        condition: "error_count < 3"
      - provider: "DeepInfra"
        model: "meta-llama/Llama-3.3-70B-Instruct"

配置加载后，任何客户端直接按名字请求即可：

from g4f.client import Client

client = Client()
response = client.chat.completions.create(
    model="my-gpt4",   # 在 config.yaml 中定义
    messages=[{"role": "user", "content": "Hello!"}],
)
print(response.choices[0].message.content)

8.3 持久化

HAR 文件、cookie 与生成的媒体统一持久化在映射目录中（Docker 场景即 har_and_cookies 与 generated_media 两个卷），重启容器不丢失登录态与产出物。

九、本地推理与媒体生成

十、贡献指南：新增提供商

标准流程：

  1. Fork 仓库并创建分支；
  2. 在 g4f/Provider/ 中实现提供商适配器；
  3. 补充配置与依赖说明；
  4. 附测试与使用示例（测试参考 etc/testing/ 与 etc/unittest/）；
  5. 尊重第三方代码许可证并正确署名；
  6. 运行测试与 linter 后提交 PR，附清晰描述。

仓库还提供了脚手架工具 etc/tool/create_provider.py 辅助生成新提供商骨架；g4f/Provider/template/ 中的 OpenaiTemplate、BackendApi 是编写适配器时可复用的模板基类。

十一、安全、隐私与下线策略

  • 不要存储或分享敏感凭据，遵循各提供商的推荐安全实践；
  • 生产部署应启用 HTTPS、认证与防火墙规则，限制对 cookie/HAR 存储的访问；
  • 若你的站点出现在项目链接中并希望移除，可发送所有权证明至 takedown@g4f.ai 申请下线。

十二、快速命令速查（Appendix）

# 安装
pip install -U g4f[all]

# 运行 GUI
python -m g4f.cli gui --port 8080 --debug
# 或
python -c "from g4f.gui import run_gui; run_gui()"

# 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

# Docker（slim）
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

Python 使用模式小结：client.chat.completions.create(...)（文本/工具调用）、client.images.generate(...)（图像）、AsyncClient 异步变体；流式补全、停止条件（stop）、系统消息与 tool-calling 模式可在示例 etc/examples/ 中找到，如 text_completions_streaming.py、messages_stream.py、vision_images.py。此外项目内置了 LangChain 与 PydanticAI 集成（g4f/integration/langchain.py、g4f/integration/pydantic_ai.py），可在生态框架中直接复用 g4f 的提供商聚合能力。

十三、项目原则与许可

GPT4Free 遵循社区原则：开放获取 AI 工具与模型、跨提供商协作、反对垄断性封闭系统、以社区为中心的开发。项目以 GNU GPLv3 许可发布：可自由再分发与修改，程序按「无担保」条款提供。完整许可文本见 LICENSE，行为准则见 CODE_OF_CONDUCT.md。核心创建者为 @xtekky，现由 @hlohaus 维护；har_file.py、PerplexityLabs.py、Gemini.py、MetaAI.py、proofofwork.py 等模块的代码输入来自多个第三方项目（对应适配器现位于 g4f/Provider/openai/har_file.py、g4f/Provider/Perplexity.py 等路径），README 中逐一署名致谢。

gpt4free
The official gpt4free repository | various collection of powerful language models | opus 4.6 gpt 5.3 kimi 2.5 deepseek v3.2 gemini 3
项目地址：https://gitcode.com/GitHub_Trending/gp/gpt4free
登录后查看全文

相关内容推荐

1 gpt4free（g4f）推理字段标准化：统一 reasoning 输出格式与双向输入兼容设计2 逆向工程驱动的AI模型访问：GPT4Free技术原理与实践指南3 如何通过GPT4Free实现AI模型自由访问：开源方案技术指南4 解密GPT4Free：AI模型逆向工程技术原理与实践指南5 GPT-4o免费访问全攻略：揭秘开源项目GPT4Free的技术突破与实战价值6 GPT4Free开源项目：免费访问AI模型的技术实践与应用指南7 突破AI访问限制：GPT4Free如何让每个人自由使用GPT-4o模型8 GPT4Free：开源AI访问方案的技术实现与实战指南9 GPT4Free：自由访问AI模型的逆向工程技术探索10 低成本高效部署：树莓派本地运行GPT4Free全指南
热门项目推荐
相关项目推荐

热门内容推荐

1 编程实践项目探索指南：从零构建技术能力体系2 技术解构式学习：从0到1构建你的编程知识体系3 构建自己的技术世界：build-your-own-x项目的实践探索指南4 解锁编程技能的实践之旅：从零构建你的技术世界5 技术实践探索：从零开始构建核心系统的实践指南6 亲手锻造技术引擎：从0到1构建核心系统的实践指南

最新内容推荐

vLLM LoRA 适配器全解析：从离线推理到动态热加载与 MoE 混合格式实战Next.js 发布通道解析：stable 与 canary 双通道机制、dist-tag 策略与发布脚本源码剖析Prometheus Remote Read API 全解：/api/v1/read 端点、外部标签语义与流式 XOR 分块Atom solarized-light-syntax：Solarized 浅色语法主题的实现解析与定制指南解析 Ponytail 的 AGENTS.md：七级决策阶梯与"懒但靠谱"的 Agent 规则文件设计get-shit-done 安装器迁移修复 3541 深度解析：非交互升级中 prompt-user 阻塞的分类解决机制Vite 官方 Qwik + TypeScript 启动模板（CSR 模式）深度解析Docling Document（DoclingDocument）深度解析：Docling 统一文档表示的字段结构、层级模型与源码实践Magisk 首次安装实战：Boot Ramdisk 判定、镜像 Patch 流程与三星设备专属路径详解Crawl4AI 自适应爬虫实战：统计与嵌入双策略、参数调优与知识库持久化

项目优选

收起
kernelkernel
deepin linux kernel
C
33
18
ops-transformerops-transformer
本项目是CANN提供的transformer类大模型算子库，实现网络在NPU上加速计算。
C++
1.12 K
2.72 K
kernelkernel
openEuler内核是openEuler操作系统的核心，既是系统性能与稳定性的基石，也是连接处理器、设备与服务的桥梁。
C
527
590
ops-nnops-nn
本项目是CANN提供的神经网络类计算算子库，实现网络在NPU上加速计算。
C++
904
1.82 K
pytorchpytorch
作为 Ascend for PyTorch 社区的核心组件，TorchNPU 是昇腾专为 PyTorch 打造的深度学习适配插件，使 PyTorch 框架能够直接调用昇腾 NPU，为开发者提供昇腾 AI 处理器的超强算力。
Python
854
1.34 K
docsdocs
暂无描述
Markdown
889
5.78 K
jiuwenswarmjiuwenswarm
JiuwenSwarm 是一款基于openJiuwen开发的智能AI Agent，它能够将大语言模型的强大能力，通过你日常使用的各类通讯应用，直接延伸至你的指尖。
Python
3.52 K
1.01 K
ops-mathops-math
本项目是CANN提供的数学类基础计算算子库，实现网络在NPU上加速计算。
C++
1.33 K
1.45 K
cann-learning-hubcann-learning-hub
CANN 学习中心仓，支持在线互动运行、边学边练，提供教程、示例与优化方案，一站式助力昇腾开发者快速上手。
Jupyter Notebook
981
502
AscendNPU-IRAscendNPU-IR
AscendNPU-IR是基于MLIR（Multi-Level Intermediate Representation）构建的，面向昇腾亲和算子编译时使用的中间表示，提供昇腾完备表达能力，通过编译优化提升昇腾AI处理器计算效率，支持通过生态框架使能昇腾AI处理器与深度调优
C++
540
384