同步客户端

相关源文件

• 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 系统提供了一个阻塞式 API 接口来访问 AI 提供商。它提供了一个简单、传统的编程模型，函数调用会阻塞直到完成，非常适合脚本、交互式应用程序以及不偏好 async/await 模式的环境。

有关异步操作，请参阅 异步客户端。有关 REST API 访问，请参阅 FastAPI 端点。

客户端架构

同步客户端围绕 Client 类构建，该类协调不同的服务组件。

来源：g4f/client/__init__.py326-340 g4f/client/__init__.py406-410 g4f/client/__init__.py341-344 g4f/client/__init__.py412-415

基本用法

Client 类是同步操作的主要入口点。

客户端可以在初始化时配置默认提供商和代理设置。

参数	类型	描述
provider	ProviderType	聊天补全的默认提供商
media_provider	ProviderType	图像生成的默认提供商
proxy	str	默认代理 URL
api_key	str	默认 API 密钥

来源：g4f/client/__init__.py326-340 etc/unittest/client.py67-70

聊天补全

Completions 类通过 create() 方法处理文本生成请求。

参数

create() 方法接受以下关键参数：

参数	类型	默认	描述
messages	消息	必填	对话消息
model	str	""	模型标识符
provider	ProviderType	None	要使用的特定提供商
流	bool	否	启用流式响应
max_tokens	int	None	最大生成 token 数量
stop	list[str]	None	停止序列
response_format	dict	None	响应格式约束

响应处理

同步客户端使用多个处理函数来处理提供商的响应。

• iter_run_tools() - 执行提供商的创建函数并处理工具调用。
• iter_response() - 处理响应流并构建补全对象。
• iter_append_model_and_provider() - 将模型和提供商元数据添加到响应中。

来源：g4f/client/__init__.py346-396 g4f/client/__init__.py60-151 g4f/client/__init__.py154-163

图像生成

Images 类通过包装异步操作，提供了同步图像生成功能。

关键方法

方法	描述
generate()	图像生成的同步包装器
create_variation()	创建现有图像的变体
async_generate()	核心异步生成逻辑
_generate_image_response()	处理特定于提供商的图像生成
_process_image_response()	处理和格式化图像响应

响应格式

图像客户端支持多种响应格式。

• url - 返回图像 URL，不进行本地缓存。
• b64_json - 返回 base64 编码的图像数据。
• None (默认) - 下载并将图像保存在本地。

来源：g4f/client/__init__.py417-429 g4f/client/__init__.py444-484 g4f/client/__init__.py532-542

响应类型

客户端根据操作返回不同的响应对象。

流式与非流式

• 非流式：返回一个包含完整响应的 ChatCompletion 对象。
• 流式：返回一个迭代器，在内容到达时产生 ChatCompletionChunk 对象。

来源：g4f/client/stubs.py174-213 g4f/client/stubs.py73-104 g4f/client/stubs.py302-317

配置和参数

模型解析

客户端支持灵活的模型指定。

提供商选择

当未指定显式提供商时，客户端遵循此层级结构：

1. 客户端的默认提供商
2. AnyProvider 以实现自动选择。
3. 从字符串名称转换提供商。

媒体处理

resolve_media() 函数标准化媒体输入。

• 将 image 参数转换为 media 列表格式。
• 处理 images 参数以实现向后兼容。
• 确保媒体项是格式正确的元组。

来源：g4f/client/__init__.py364-376 g4f/client/__init__.py48-57 g4f/client/service.py25

与提供商系统集成

同步客户端通过几个关键机制与提供商系统集成。

参数过滤

filter_none() 辅助函数在将参数传递给提供商之前移除 None 值，以确保 API 调用干净并防止提供商错误。

工具集成

iter_run_tools() 函数处理：

• 聊天补全期间的工具调用执行。
• 特定于提供商的工具实现。
• 将工具响应集成到对话流程中。

来源： g4f/client/__init__.py377-389 g4f/client/helper.py26 g4f/tools/run_tools.py21