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本文以 GPT4Freeg4f官方 README 为主体系统讲解这个多 LLM 提供商聚合框架的安装部署Docker / 精简镜像 / pip / 源码、三种运行形态Web GUI、OpenAI 兼容 API、MCP 服务器、Python 同步/异步客户端的完整用法以及如何通过环境变量与config.yaml进行模型路由定制结合仓库源码可进一步印证客户端的提供商回退逻辑与配置加载机制帮助你把一个「一个入口、多家模型」的 LLM 服务真正跑起来。一、项目定位它包含什么GPT4Free 是一个社区驱动的聚合项目它将多个可访问的 LLM 与媒体生成提供商统一在一套接口之后让用户不必关心底层是哪家 API。根据 README 的 Whats 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 与 arm64slim 镜像两者都支持参见 docs/aarch64-compatibility.md部分提供商适配器需要平台级工具Chrome/Chromium 等具体以各提供商文档为准。三、安装方式3.1 Docker推荐创建持久化目录并设置属主容器内运行用户 UID/GID 为 1200:1201mkdir -p ${PWD}/har_and_cookies ${PWD}/generated_media sudo chown -R 1200:1201 ${PWD}/har_and_cookies ${PWD}/generated_media拉取并启动镜像docker pull hlohaus789/g4f docker run -p 8080:8080 -p 7900:7900 \ --shm-size2g \ -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-size2g是浏览器自动化任务的关键参数负载更重时建议继续加大两个卷的作用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 与 arm64mkdir -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/v1Swagger UI 在http://localhost:1337/docs。slim 镜像可在启动时更新 g4f 包并按需安装额外依赖。仓库根目录提供了现成的编排文件 docker-compose.yml 与 docker-compose-slim.yml 可直接参考。3.3 Windows.exe 启动器从项目 Releases 页面下载g4f.exe.zip并解压运行g4f.exeWindows 启动器另有独立仓库 g4f/g4f.exe浏览器打开http://localhost:8080/chat/即进入 GUI若 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 GUIWeb 客户端两种方式等价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 APIpython -m g4f --port 8080 --debugpython -m g4f会执行 g4f/main.py 中的 CLI 入口。在 slim Docker 映射方式下API 通常位于http://localhost:1337/v1OpenAPI/Swagger UI 位于http://localhost:1337/docs。API 主体实现在 g4f/api/run.py 与 g4f/api/init.py它提供 OpenAI 风格的chat/completions等端点由 GPT4Free 的提供商选择机制在幕后完成路由——即「OpenAI 式工作流多提供商透明转发」。4.3 CLI 与 MCP 服务器MCPModel 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 3000HTTP 模式提供两个端点POST http://localhost:8765/mcpJSON-RPC与GET http://localhost:8765/health健康检查。配合 Claude Desktop在claude_desktop_config.json中加入{ mcpServers: { gpt4free: { command: python, args: [-m, g4f.mcp] } } }README 列出的 MCP 工具有web_searchDuckDuckGo 搜索、web_scrape网页正文抽取、image_generation文生图。仓库中附带了配置示例 g4f/mcp/claude_desktop_config.example.json服务器实现见 g4f/mcp/server.py 与工具定义 g4f/mcp/tools.py。4.4 容器内桌面登录可选访问http://localhost:7900/?autoconnect1resizescalepasswordsecret该桌面用于登录 Web 版提供商从而导出 cookie/HAR 文件供后续请求复用。五、Python 客户端用法pip install -U g4f[all]5.1 同步文本请求from g4f.client import Client client Client() response client.chat.completions.create( modelgpt-4o-mini, messages[{role: user, content: Hello, how are you?}], web_searchFalse ) 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( modelflux, prompta white siamese cat, response_formaturl ) print(fGenerated 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( modelgpt-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_formatjson_object时会对返回内容做filter_json清洗、max_tokens、stop、ignore_stream、raw等。另一个值得注意的机制在 g4f/client/factory.py 的create_custom_providerL17-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最终无媒体响应时抛出NoMediaResponseErrorresponse_format支持url返回原始 URL、b64_json抓取并转 base64与默认值下载并持久化到媒体目录由 g4f/image/copy_images.py 的copy_media完成落盘。六、GPT4Free.js浏览器端 JS 客户端官方 JS 客户端可直接在浏览器中使用无需自建后端script typemodule 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 / tokenneeds_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-L45DEFAULT_PORT 1337 DEFAULT_TIMEOUT 600 DEFAULT_STREAM_TIMEOUT 120 DEFAULT_MODEL openai/gpt-oss-120b配置文件目录按平台解析Linux 默认~/.config/g4f若已存在~/.g4f则优先Windows 为%APPDATA%/g4fmacOS 为~/Library/Application Support/g4fcookie 目录为config_dir/cookies另有本地快捷目录./har_and_cookiesL36-L37。AppConfig.load_from_env读取的环境变量包括环境变量作用G4F_API_KEYg4f 自定义 API 密钥G4F_TIMEOUT全局超时默认 600 秒G4F_STREAM_TIMEOUT流式超时默认 120 秒G4F_PROXY代理地址G4F_MODEL/G4F_PROVIDER默认模型 / 默认提供商G4F_DISABLE_CUSTOM_API_KEY禁用自定义 API key8.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: ...键必填说明name✅客户端使用的模型名providers✅有序的提供商候选列表provider✅提供商类名如OpenaiAccount、PollinationsAImodel转发给提供商的模型名缺省取路由namecondition布尔表达式控制该提供商是否可选condition可引用三类变量quota提供商get_quota()返回的完整字典内存缓存 5 分钟 TTL收到 HTTP 429 时立即失效支持点号访问嵌套字段缺失键解析为0.0。各提供商格式不同例如PollinationsAI返回{balance: float}Yupp返回{credits: {remaining: int, total: int}}balancequota.balance的简写别名为 PollinationsAI 兼容性保留error_count该提供商最近 1 小时内记录的错误数超过 1 小时的错误自动清理。支持运算符 !与逻辑连接词and or not、括号分组。完整示例见 etc/examples/config.yamlmodels: - 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( modelmy-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.pyOllama 服务两种后端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。十、贡献指南新增提供商标准流程Fork 仓库并创建分支在g4f/Provider/中实现提供商适配器补充配置与依赖说明附测试与使用示例测试参考 etc/testing/ 与 etc/unittest/尊重第三方代码许可证并正确署名运行测试与 linter 后提交 PR附清晰描述。仓库还提供了脚手架工具 etc/tool/create_provider.py 辅助生成新提供商骨架g4f/Provider/template/ 中的OpenaiTemplate、BackendApi是编写适配器时可复用的模板基类。十一、安全、隐私与下线策略不要存储或分享敏感凭据遵循各提供商的推荐安全实践生产部署应启用 HTTPS、认证与防火墙规则限制对 cookie/HAR 存储的访问若你的站点出现在项目链接中并希望移除可发送所有权证明至 takedowng4f.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-size2g \ -v ${PWD}/har_and_cookies:/app/har_and_cookies \ -v ${PWD}/generated_media:/app/generated_media \ hlohaus789/g4f:latest # Dockerslim 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-slimPython 使用模式小结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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

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

相关推荐

Jibber Jabber 语言检测库解析：lazygit 国际化自动识别 UI 语言的底层机制

BenchMIRT入门：从题目层面审计LLM基准测试的污染与捷径

dnSpy 6.1.8-net472：.NET Framework逆向调试的终极兼容版本

更多资讯

Dify 官方安装包 Docker Compose 部署避坑与验证

OSG3.6.5+OSGEarth在VS2019下的3rdParty配置与排错

Dify Docker Compose部署与RAG知识库验证避坑指南

ObjectArx 2010屏幕菜单可停靠面板开发避坑

程序员写作五年：写文章如何反过来提升了我的代码水平

一种需求驱动的动态元素语义定义机制：面向知识元素理解的语义字典方法

今日更新

微信个人号API开发案例：图片/语音/视频消息怎么下载解析存到本地？

Python股票自动交易系统源码解析：从行情获取到风控的完整链路

视酷酷信IM源码部署指南：Java 17+MySQL 8.0.33实战配置

本周精选

防幻觉智能体架构：电源硬件设计中的大模型编排与工具化实践

OpenGL面试核心考点：渲染管线、矩阵变换与性能排查全解析

全国计算机二级C语言真题PDF高效刷题指南

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？