客户端接口

相关源文件

• etc/tool/commit.py
• etc/unittest/client.py
• etc/unittest/models.py
• g4f/Provider/Cloudflare.py
• g4f/Provider/Copilot.py
• g4f/Provider/har/__init__.py
• g4f/Provider/hf_space/Qwen_Qwen_3.py
• g4f/Provider/hf_space/__init__.py
• g4f/api/__init__.py
• g4f/client/__init__.py
• g4f/client/stubs.py
• g4f/providers/any_provider.py

本文档介绍了用户和应用程序与 g4f 系统交互的各种方式。g4f 库提供了多种客户端接口，以适应不同的用例、编程范例和集成需求。有关这些客户端使用的底层提供程序系统的信息，请参阅提供程序系统。有关 API 端点实现细节，请参阅API。

接口概述

g4f 系统提供四个主要的客户端接口，每个接口都针对特定的用例和集成模式而设计。

来源： g4f/client/__init__.py326-632 g4f/api/__init__.py72-103

同步 Python 客户端

Client 类为偏好阻塞操作或不需要异步功能的应用程序提供了同步接口。

客户端架构

来源： g4f/client/__init__.py326-340 g4f/client/__init__.py341-411 g4f/client/__init__.py412-616

核心方法

Completions.create() 方法是文本生成的主要接口。

参数	类型	描述
messages	消息	OpenAI 格式的对话消息
model	str	模型标识符或留空以自动选择
流	bool	启用流式响应
proxy	str	HTTP 代理配置
image	ImageType	视觉模型的单个图像
response_format	dict	输出格式规范
max_tokens	int	最大响应长度
stop	list[str]	停止序列

来源： g4f/client/__init__.py346-397

异步 Python 客户端

AsyncClient 类提供与同步客户端相同的功能，但具有异步/await 支持，用于非阻塞操作。

异步客户端组件

来源： g4f/client/__init__.py617-632 g4f/client/__init__.py633-704 g4f/client/__init__.py705-731

异步响应处理

异步客户端使用复杂的管道来处理响应。

1. async_iter_run_tools() - 处理工具执行和提供程序路由
2. async_iter_response() - 处理流式响应和格式化输出
3. async_iter_append_model_and_provider() - 向响应块添加元数据

来源： g4f/client/__init__.py165-258 g4f/client/__init__.py307-324

REST API 接口

基于 FastAPI 的 REST API 提供了兼容 OpenAI 的端点，用于与现有工具和框架集成。

API 架构

来源： g4f/api/__init__.py72-103 g4f/api/__init__.py152-223 g4f/api/__init__.py239-263

关键 API 端点

端点	方法	目的	配置
/v1/chat/completions	POST	文本生成	ChatCompletionsConfig
/v1/images/generate	POST	图像生成	ImageGenerationConfig
/v1/models	GET	列出可用模型	None
/v1/providers	GET	列出提供程序	None
/v1/audio/transcriptions	POST	音频转录	UploadFile

来源： g4f/api/__init__.py312-397 g4f/api/__init__.py474-506 g4f/api/__init__.py239-263

请求流程

来源： g4f/api/__init__.py312-397 g4f/client/__init__.py644-696

配置与集成

全局配置

AppConfig 类提供影响所有客户端接口的系统范围配置。

设置	类型	目的
ignored_providers	list[str]	要排除的提供商
g4f_api_key	str	API 认证密钥
ignore_cookie_files	bool	跳过基于 cookie 的身份验证
model	str	默认模型覆盖
provider	str	默认提供商覆盖
proxy	str	全局代理配置

来源： g4f/api/__init__.py136-151

客户端初始化

来源： g4f/client/__init__.py326-340 g4f/client/service.py g4f/providers/any_provider.py38-268

响应类型集成

所有客户端接口都聚合到通用的响应类型，提供一致的数据结构。

响应类型	用途	关键属性
ChatCompletion	非流式文本	choices, usage, model, provider
ChatCompletionChunk	流式文本	choices, delta, finish_reason
ImagesResponse	图像生成	data, model, provider, created
ClientResponse	通用响应	output, usage, conversation

来源: g4f/client/stubs.py174-250 g4f/client/stubs.py73-111 g4f/client/stubs.py302-317