GPT4Free (g4f)

由 @xtekky 创建，
由 @hlohaus 维护

欢迎通过 GitHub Sponsors ❤️

实时演示与文档：https://g4f.dev | 文档：https://g4f.dev/docs

---

GPT4Free (g4f) 是一个社区驱动的项目，汇集了多个易于访问的提供商和接口，旨在让使用现代 LLM 和媒体生成模型更加简单灵活。GPT4Free 的目标是提供多提供商支持、本地 GUI、兼容 OpenAI 的 REST API，以及便捷的 Python 和 JavaScript 客户端——所有这些都遵循社区优先的许可协议。

本 README 是一份整合、改进且完整的指南，用于安装、运行和参与 GPT4Free 的开发。

目录

• 包含的内容
• 快速链接
• 要求与兼容性
• 安装
  • Docker（推荐）
  • 精简 Docker 镜像
  • Windows (.exe)
  • Python（pip / 源码安装 / 部分安装）
• 运行应用
  • GUI（Web 客户端）
  • FastAPI / 干预 API
  • 命令行界面
  • 可选的提供商登录（容器内的桌面）
• 使用 Python 客户端
  • 同步文本示例
  • 图像生成示例
  • 异步客户端示例
• 使用 GPT4Free.js（浏览器 JS 客户端）
• 提供商与模型（概述）
• 本地推理与媒体
• 配置与定制
• 在智能手机上运行
• 干预 API（兼容 OpenAI）
• 示例与常见模式
• 贡献
  • 如何创建新的提供商
  • AI 如何帮助你编写代码
• 安全、隐私与下架政策
• 致谢、贡献者与署名
• 技术支持亮点
• 变更日志与发布
• 宣言 / 项目原则
• 许可证
• 联系与赞助
• 附录：快速命令与示例

---

包含的内容

• Python 客户端库和异步客户端。
• 可选的本地 Web GUI。
• 基于 FastAPI 的兼容 OpenAI 的 API（干预 API）。
• 官方浏览器 JS 客户端（g4f.dev 发布版）。
• Docker 镜像（完整版和精简版）。
• 多提供商适配器（LLM、媒体提供商、本地推理后端）。
• 用于图像/音频/视频生成及媒体持久化的工具。

---

快速链接

• 官网与文档：https://g4f.dev | https://g4f.dev/docs
• PyPI：https://pypi.org/project/g4f
• Docker 镜像：https://hub.docker.com/r/hlohaus789/g4f
• 发布版本：https://github.com/xtekky/gpt4free/releases
• 问题追踪：https://github.com/xtekky/gpt4free/issues
• 社区：Telegram（https://telegram.me/g4f_channel）· Discord 新闻（https://discord.gg/5E39JUWUFa）· Discord 支持（https://discord.gg/qXA4Wf4Fsm）

---

要求与兼容性

• 推荐使用 Python 3.10 或更高版本。
• 对于使用浏览器自动化技术的提供商，需要 Google Chrome/Chromium。
• 使用 Docker 进行容器化部署。
• 支持 x86_64 和 arm64 架构（精简镜像同时支持两者）。
• 部分提供商适配器可能需要特定平台的工具（如 Chrome/Chromium 等），详情请参阅相应提供商的文档。

---

安装

Docker（推荐）

1. 安装 Docker：https://docs.docker.com/get-docker/
2. 创建持久化目录：
   • 示例（Linux/macOS）：

     mkdir -p ${PWD}/har_and_cookies ${PWD}/generated_media
     sudo chown -R 1200:1201 ${PWD}/har_and_cookies ${PWD}/generated_media
     

3. 拉取镜像：

   docker pull hlohaus789/g4f
   

4. 运行容器：

   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 的桌面，以进行提供商登录（可选）。
• 对于较重的浏览器自动化任务，可适当增加 --shm-size 参数。

精简 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

注意事项：

• 精简镜像可以在启动时更新 g4f 包，并根据需要安装额外的依赖项。
• 在此示例中，干预 API 映射到了 1337 端口。

Windows 指南 (.exe)

👉 请查看 GPT4Free 的 Windows 启动器：
🔗 https://github.com/gpt4free/g4f.exe 🚀

1. 从以下链接下载发布文件 g4f.exe.zip： https://github.com/xtekky/gpt4free/releases/latest
2. 解压并运行 g4f.exe。
3. 打开 GUI：http://localhost:8080/chat/
4. 如果 Windows 防火墙阻止访问，请允许该应用程序。

Python 安装（通过 pip / 从源码安装 / 部分安装）

先决条件：

• Python 3.10+（https://www.python.org/downloads/）
• 某些提供商需要 Chrome/Chromium。

从 PyPI 安装（推荐）：

pip install -U g4f[all]

部分安装

• 若要仅安装特定功能，请使用可选的 extras 组。详情请参阅项目文档中的 docs/requirements.md。

从源码安装：

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

注意事项：

• 某些功能需要 Chrome/Chromium 或其他工具；请遵循各提供商的专用文档。

---

运行应用

GUI（Web 客户端）

• 通过 Python 运行：

from g4f.gui import run_gui
run_gui()

• 或者通过命令行：

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

• 打开：http://localhost:8080/chat/

FastAPI / 干预 API

• 启动 FastAPI 服务器：

python -m g4f --port 8080 --debug

• 如果使用精简 Docker 映射，干预 API 可能在 http://localhost:1337/v1 提供。
• Swagger UI：http://localhost:1337/docs

命令行

• 启动 GUI 服务器：

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

MCP 服务器

GPT4Free 现在包含一个模型上下文协议（MCP）服务器，允许像 Claude 这样的 AI 助手访问网络搜索、网页抓取和图像生成功能。

启动 MCP 服务器（stdio 模式）：

# 使用 g4f 命令
g4f mcp

# 或使用 Python 模块
python -m g4f.mcp

启动 MCP 服务器（HTTP 模式）：

# 在端口 8765 上启动 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"]
    }
  }
}

可用的 MCP 工具：

• web_search - 使用 DuckDuckGo 搜索网络
• web_scrape - 从网页中提取文本内容
• image_generation - 根据文本提示生成图像

有关 MCP 的详细文档，请参阅 g4f/mcp/README.md。

可选的提供商登录（容器内的桌面）

• 可通过以下地址访问：

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

• 对于登录基于 Web 的提供商以获取 Cookie/HAR 文件非常有用。

---

使用 Python 客户端

安装：

pip install -U g4f[all]

同步文本示例：

from g4f.client import Client

client = Client()
response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "你好，最近怎么样？"}],
    web_search=False
)
print(response.choices[0].message.content)

预期输出：

你好！今天有什么可以帮您的吗？

图像生成示例：

from g4f.client import Client

client = Client()
response = client.images.generate(
    model="flux",
    prompt="一只白色的暹罗猫",
    response_format="url"
)
print(f"生成的图像 URL：{response.data[0].url}")

异步客户端示例：

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": "请简要解释一下量子计算"}],
    )
    print(response.choices[0].message.content)

asyncio.run(main())

注意事项：

• 请参阅完整的 API 参考，了解流式传输、工具调用模式以及高级选项：https://g4f.dev/docs/client

---

使用 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',  // 或 "gpt-4o"、"deepseek-v3" 等
      messages: [{ role: 'user', content: '请解释一下量子计算' }]
  });
  console.log(result.choices[0].message.content);
</script>

注意事项：

• JS 客户端通过 g4f.dev CDN 分发，便于使用。请查看 CORS 相关注意事项及使用限制。

---

提供商与模型（概述）

• GPT4Free 集成了众多提供商，包括但不限于兼容 OpenAI 的端点、PerplexityLabs、Gemini、MetaAI、Pollinations（媒体）以及本地推理后端。
• 模型的可用性和行为取决于提供商的能力。有关当前支持的提供商和模型列表，请参阅提供商文档：https://g4f.dev/docs/providers-and-models

提供商要求可能包括：

• API 密钥或令牌（用于认证提供商）
• 浏览器 Cookie / HAR 文件（用于通过浏览器自动化抓取的提供商）
• Chrome/Chromium 或无头浏览器工具
• 本地模型二进制文件和运行时环境（用于本地推理）

---

本地推理与媒体

• GPT4Free 支持本地推理后端。有关支持的运行时和硬件指导，请参阅 docs/local.md。
• 媒体生成（图像、音频、视频）可通过提供商实现（例如 Pollinations）。有关格式、选项和使用示例，请参阅 docs/media.md。

---

配置与定制

• 可通过环境变量、CLI 标志或配置文件进行配置。详情请参阅 docs/config.md。
• 为减小安装体积，可使用部分依赖组。详情请参阅 docs/requirements.md。
• 提供商选择：了解如何设置默认值以及按请求覆盖，请参阅 docs/selecting_a_provider.md。
• 持久化：HAR 文件、Cookie 和生成的媒体会保存在映射目录中（例如 har_and_cookies、generated_media）。

---

在智能手机上运行

• Web GUI 具有响应式设计，可以通过手机访问，只需访问你的主机 IP:8080 或通过隧道访问。详情请参阅 docs/guides/phone.md。

---

干预 API（兼容 OpenAI）

• 干预 API 能够实现通过 GPT4Free 提供商选择路由的类似 OpenAI 的工作流。
• 文档：docs/interference-api.md
• 默认端点（示例精简 Docker）：http://localhost:1337/v1
• Swagger UI：http://localhost:1337/docs

---

示例与常见模式

• 流式完成、停止条件、系统消息以及工具调用模式的文档如下：
  • docs/client.md
  • docs/async_client.md
  • docs/requests.md
• 集成（LangChain、PydanticAI）：docs/pydantic_ai.md
• 旧版示例：docs/legacy.md

---

贡献

我们欢迎各种形式的贡献——新的提供商、功能、文档和修复都将受到高度赞赏。

如何贡献：

1. 克隆并分支仓库。
2. 为您的更改创建一个新分支。
3. 运行测试和代码检查工具。
4. 提交带有清晰描述及必要测试或示例的拉取请求。

仓库地址：https://github.com/xtekky/gpt4free

如何创建一个新的提供商

• 请阅读指南：docs/guides/create_provider.md
• 一般步骤如下：
  • 在 g4f/Provider/ 目录下实现一个提供商适配器。
  • 添加配置说明和依赖项注释。
  • 包含测试用例和使用示例。
  • 尊重第三方代码的许可协议，并正确注明出处。

AI 如何帮助您编写代码

• 请参阅：docs/guides/help_me.md，其中提供了加速开发的提示模板和工作流程。

---

安全、隐私与下架政策

• 请勿存储或分享敏感凭据。请遵循各提供商推荐的安全实践。
• 如果您的网站出现在本项目的链接中，且希望将其移除，请向 takedown@g4f.ai 发送所有权证明，我们将尽快处理。
• 对于生产环境，请通过 HTTPS、身份验证和防火墙规则保护服务器安全。限制对提供商凭据以及 Cookie/HAR 文件存储的访问权限。

---

致谢、贡献者与署名

• 核心创建者：@xtekky（原作者），由 @hlohaus 维护。
• 完整贡献者图谱：https://github.com/xtekky/gpt4free/graphs/contributors
• 值得一提的代码贡献及署名来源：
  • har_file.py — 来自 xqdoo00o/ChatGPT-to-API
  • PerplexityLabs.py — 来自 nathanrchn/perplexityai
  • Gemini.py — 来自 dsdanielpark/Gemini-API 和 HanaokaYuzu/Gemini-API
  • MetaAI.py — 灵感来源于 Strvm 的 meta-ai-api
  • proofofwork.py — 来自 missuo/FreeGPT35

此外，还有许多其他贡献者在仓库中被特别提及。

---

技术支持项目亮点

• Pollinations AI — 生成式媒体：https://github.com/pollinations/pollinations
• MoneyPrinter V2 — 使用 GPT4Free 的示例项目：https://github.com/FujiwaraChoki/MoneyPrinterV2
• 关于使用 GPT4Free 的完整项目和站点列表，请参阅：docs/powered-by.md

---

更改记录与发布版本

• 发布版本及完整更改记录：https://github.com/xtekky/gpt4free/releases
• 订阅 Discord 或 Telegram 以获取最新公告。

---

宣言 / 项目原则

GPT4Free 以社区原则为指导：

1. 开放获取人工智能工具和模型。
2. 各提供商及项目之间的协作。
3. 反对限制创造力的垄断性封闭系统。
4. 以社区为中心的开发，促进人工智能技术的广泛普及。
5. 推动创新、创造性和可及性。

https://g4f.dev/manifest

---

许可证

本程序采用 GNU 通用公共许可证 v3.0（GPLv3）授权。完整许可证内容请参见：https://www.gnu.org/licenses/gpl-3.0.txt

简要说明：

• 您可以根据 GPLv3 的条款重新分发和/或修改本程序。
• 本程序“按原样”提供，不附带任何担保。

版权声明：

xtekky/gpt4free: 版权所有 © 2025 xtekky

本程序是自由软件：您可以根据自由软件基金会发布的 GNU 通用公共许可证的条款重新分发或修改它，无论是第 3 版还是之后的任何版本（由您选择）。

本程序旨在为您提供便利，但不提供任何形式的担保，包括对适销性或特定用途适用性的隐含担保。有关详细信息，请参阅 GNU 通用公共许可证。

---

联系方式与赞助

• 维护者：https://github.com/hlohaus
• 赞助：https://github.com/sponsors/hlohaus
• 问题与功能请求：https://github.com/xtekky/gpt4free/issues
• 下架请求：takedown@g4f.ai

---

附录：快速命令与示例

安装（pip）：

pip install -U g4f[all]

运行 GUI（Python）：

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（精简版）：

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 实现。

文档与深入阅读

• 完整文档：https://g4f.dev/docs
• 客户端 API 文档：https://g4f.dev/docs/client
• 异步客户端文档：https://g4f.dev/docs/async_client
• 提供商指南：https://g4f.dev/docs/guides
• 本地推理：https://g4f.dev/docs/local

---

感谢您使用并为 GPT4Free 做出贡献——让我们携手共建一个开放、灵活且以社区驱动的强大 AI 工具平台。

GPT4Free (g4f) 快速上手指南

GPT4Free 是一个社区驱动的项目，旨在聚合多种可用的 LLM 和媒体生成模型提供商，提供统一的 Python/JS 客户端、本地 Web GUI 以及兼容 OpenAI 的 API 接口。

环境准备

在开始之前，请确保您的系统满足以下要求：

• 操作系统：Linux, macOS, Windows (x86_64 或 arm64)。
• Python 版本：推荐 Python 3.10 或更高版本。
• 浏览器依赖：部分提供商需要 Google Chrome 或 Chromium 以支持浏览器自动化。
• 容器化（可选）：若使用 Docker 部署，需安装 Docker Engine。

提示：国内用户若遇到 PyPI 下载缓慢问题，可使用清华或阿里镜像源加速安装。

安装步骤

您可以选择以下任意一种方式进行安装：

方式一：Python pip 安装（推荐）

直接使用 pip 安装完整功能包：

pip install -U g4f[all] -i https://pypi.tuna.tsinghua.edu.cn/simple

若需从源码安装：

git clone https://github.com/xtekky/gpt4free.git
cd gpt4free
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
pip install -e .

方式二：Docker 部署（推荐用于生产环境）

1. 创建持久化目录并设置权限：

   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
   

方式三：Windows 免安装版

1. 从 Releases 页面 下载 g4f.exe.zip。
2. 解压后双击运行 g4f.exe。
3. 若被防火墙拦截，请在弹窗中允许访问。

基本使用

安装完成后，您可以通过以下三种方式使用 GPT4Free。

1. 启动 Web GUI 界面

最简单的方式是启动内置的网页聊天界面：

通过命令行启动：

python -m g4f.cli gui --port 8080

或通过 Python 代码启动：

from g4f.gui import run_gui
run_gui()

启动后，在浏览器访问：http://localhost:8080/chat/

2. Python 客户端调用

创建一个 Python 脚本（例如 test.py），输入以下代码即可调用大模型：

from g4f.client import Client

client = Client()
response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "你好，请介绍一下你自己"}],
    web_search=False
)
print(response.choices[0].message.content)

生成图片示例：

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}")

3. 浏览器 JS 客户端调用

无需后端，直接在 HTML 文件中引入官方 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',
      messages: [{ role: 'user', content: '用中文解释量子计算' }]
  });
  console.log(result.choices[0].message.content);
</script>

4. 开启 OpenAI 兼容 API

若需让其他应用（如 NextChat, OneAPI）接入，可启动 FastAPI 服务：

python -m g4f --port 8080

API 端点地址为：http://localhost:8080/v1 Swagger 文档地址：http://localhost:8080/docs