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

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

【免费下载链接】gpt4freeThe 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 服务真正跑起来。

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

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

2. 拉取并启动镜像：

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（媒体）以及本地推理后端。模型可用性与行为取决于具体提供商能力。

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

密钥通过环境变量注入，参考 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读取的环境变量包括：

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

g4f 支持把config.yaml放在 cookie 目录（与.har/.jsoncookie 文件同目录，如~/.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: "..."

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两个卷），重启容器不丢失登录态与产出物。

九、本地推理与媒体生成

• 本地推理：g4f 支持本地推理后端，g4f/Provider/local/ 下提供Local.py（直接本地模型）与Ollama.py（Ollama 服务）两种后端，g4f/local/与g4f/locals/中还有对应的封装模块；
• 媒体生成：图像、音频、视频通过提供商实现，例如 g4f/Provider/PollinationsImage.py、g4f/Provider/audio/（EdgeTTS、ElevenLabs、gTTS 等）、g4f/Provider/needs_auth/hf/（HuggingFace 媒体模型）以及 HF Space 上的 Flux/SD3.5 适配器 g4f/Provider/hf_space/。客户端统一入口为client.images.generate(...)（client.media为同义别名，见 g4f/client/init.py L346-L347）。

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

标准流程：

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 中逐一署名致谢。

【免费下载链接】gpt4freeThe 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