evofabric.core.clients

evofabric.core.clients#

Chat Clients#

class evofabric.core.clients.ChatClientBase#

获取大模型Chat模式响应的基类

async create_on_stream(self, messages: Sequence[StateMessage], **kwargs) → AsyncGenerator[ChatStreamChunk, LLMChatResponse]#

流式获取大模型的响应。

参数:

  • messages (Sequence[StateMessage]) -- 表示多轮历史对话消息序列。

  • **kwargs -- 其他模型推理时需要设置的配置参数

返回:

一个异步生成器，流式过程中会持续返回 ChatStreamChunk 对象记录流式消息，最后返回大模型的响应结果 LLMChatResponse

返回类型:

AsyncGenerator[ChatStreamChunk, LLMChatResponse]

async create(self, messages: Sequence[StateMessage], **kwargs) → LLMChatResponse#

非流式获取大模型的响应

参数:

  • messages (Sequence[StateMessage]) -- 表示多轮历史对话消息序列。

  • **kwargs -- 其他模型推理时需要设置的配置参数

返回:

大模型的响应结果 LLMChatResponse

class evofabric.core.clients.OpenAIChatClient(ChatClientBase)#

基于 OpenAI 接口的 Chat 客户端实现，继承自 ChatClientBase 。

参数:

  • model (str) -- 要使用的 OpenAI 模型名称，如 "gpt-3.5-turbo"、"gpt-4" 等。

  • stream (bool) -- 是否默认以流式方式请求模型；为 True 时，调用 create_on_stream()；为 False 时，调用 create()。

  • client_kwargs (Dict) -- 用于初始化 openai.AsyncOpenAI 客户端的额外关键字参数，例如 base_url、api_key、timeout 等。

  • http_client_kwargs (Dict) -- 用于初始化底层 httpx.AsyncClient 的关键字参数，例如 proxy、limits、verify 等。

  • inference_kwargs (Dict) -- 每次调用 chat.completions.create() 时传递的推理参数，如 temperature、top_p、max_tokens 等。

  • stream_parser (Callable) -- 一个异步可调用对象，用于逐块解析 OpenAI 返回的流式数据包，需满足 AsyncIterator[str] -> ChatStreamChunk 的协议。

async create_on_stream(self, messages: Sequence[StateMessage], **kwargs) → AsyncGenerator[ChatStreamChunk, LLMChatResponse]#

流式获取大模型的响应。

参数:

  • messages (Sequence[StateMessage]) -- 表示多轮历史对话消息序列。

  • kwargs -- 其他模型推理时需要设置的配置参数（会覆盖类属性 inference_kwargs 中的同名参数）

返回:

一个异步生成器，流式过程中会持续返回 ChatStreamChunk 对象记录流式消息，最后返回大模型的响应结果 LLMChatResponse

返回类型:

AsyncGenerator[ChatStreamChunk, LLMChatResponse]

async create(self, messages: Sequence[StateMessage], **kwargs) → LLMChatResponse#

非流式获取大模型的响应。

参数:

  • messages (Sequence[StateMessage]) -- 表示多轮历史对话消息序列。

  • **kwargs -- 其他模型推理时需要设置的配置参数（会覆盖类属性 inference_kwargs 中的同名参数）

返回:

大模型的响应结果 LLMChatResponse

返回类型:

LLMChatResponse

class evofabric.core.clients.PanguClient(OpenAIChatClient)#

基于盘古大模型接口的 Chat 客户端实现，继承自 OpenAIChatClient 。

参数:

  • model (str) -- 要使用的模型名称。

  • stream (bool) -- 是否默认以流式方式请求模型；为 True 时，调用 create_on_stream()；为 False 时，调用 create()。

  • client_kwargs (Dict) -- 用于初始化 openai.AsyncOpenAI 客户端的额外关键字参数，例如 base_url、api_key、timeout 等。

  • http_client_kwargs (Dict) -- 用于初始化底层 httpx.AsyncClient 的关键字参数，例如 proxy、limits、verify 等。

  • inference_kwargs (Dict) -- 每次调用 chat.completions.create() 时传递的推理参数，如 temperature、top_p、max_tokens 等。

  • stream_parser (Callable) -- 一个异步可调用对象，用于逐块解析盘古返回的流式数据包，需满足 AsyncIterator[str] -> ChatStreamChunk 的协议。

  • enable_think (bool) -- 是否启用“思考”模式。

async create_on_stream(self, messages: Sequence[StateMessage], **kwargs) → AsyncGenerator[ChatStreamChunk, LLMChatResponse]#

流式获取大模型的响应。

参数:

  • messages (Sequence[StateMessage]) -- 表示多轮历史对话消息序列。

  • kwargs -- 其他模型推理时需要设置的配置参数（会覆盖类属性 inference_kwargs 中的同名参数）

返回:

一个异步生成器，流式过程中会持续返回 ChatStreamChunk 对象记录流式消息，最后返回大模型的响应结果 LLMChatResponse

返回类型:

AsyncGenerator[ChatStreamChunk, LLMChatResponse]

async create(self, messages: Sequence[StateMessage], **kwargs) → LLMChatResponse#

非流式获取大模型的响应。

参数:

  • messages (Sequence[StateMessage]) -- 表示多轮历史对话消息序列。

  • **kwargs -- 其他模型推理时需要设置的配置参数（会覆盖类属性 inference_kwargs 中的同名参数）

返回:

大模型的响应结果 LLMChatResponse

返回类型:

LLMChatResponse

Embedding Clients#

class evofabric.core.clients.EmbedClientBase#

与任意后端嵌入模型交互的基类客户端。 兼容 LangChain OpenAI 嵌入格式，可直接用于 LangChain、ChromaDB 等生态。

embed_query(self, text: str) → list[float]#

同步生成单段文本的嵌入向量。

参数:

text (str) -- 待嵌入的文本字符串。

返回:

长度为 embedding_dim 的浮点向量。

返回类型:

list[float]

embed_documents(self, texts: list[str], **kwargs) → list[list[float]]#

同步生成多段文本的嵌入向量列表。

参数:

  • texts (list[str]) -- 文本字符串列表。

  • kwargs (Any) -- 额外推理参数，如 chunk_size、retry 等。

返回:

与 texts 顺序对应的向量列表，每条向量长度为 embedding_dim。

返回类型:

list[list[float]]

async aembed_query(self, text: str, **kwargs) → list[float]#

异步生成单段文本的嵌入向量。

参数:

  • text (str) -- 待嵌入的文本字符串。

  • kwargs (Any) -- 额外推理参数。

返回:

长度为 embedding_dim 的浮点向量。

返回类型:

list[float]

async aembed_documents(self, texts: list[str], **kwargs) → AsyncGenerator[list[list[float]], None]#

异步生成多段文本的嵌入向量列表。

参数:

  • texts (list[str]) -- 文本字符串列表。

  • kwargs (Any) -- 额外推理参数，如 chunk_size、retry 等。

返回:

与 texts 顺序对应的向量列表，每条向量长度为 embedding_dim。

返回类型:

list[list[float]]

class evofabric.core.clients.OpenAIEmbedClient(EmbedClientBase)#

基于 OpenAI 接口规范的嵌入模型客户端，支持同步与异步批量嵌入，兼容 Ollama 等 OpenAI-Format 后端。

参数:

  • base_url (Optional[str]) -- 请求端点 URL，默认空字符串时使用官方地址。

  • api_key (Optional[str]) -- 服务访问密钥，默认空字符串时尝试读取环境变量或本地配置。

  • model (str) -- 要调用的嵌入模型名称，例如 text-embedding-3-small。

  • dimensions (Optional[int]) -- 指定返回向量的维度；模型支持降维时生效，留空则使用模型默认维度。

  • max_retries (Optional[int]) -- 请求失败时的最大重试次数，默认 2。

  • request_timeout (Optional[Union[float, tuple, Any]]) -- 单次请求最长等待时间（秒），支持浮点数或 (connect, read) 元组。

model_post_init(self, context: Any, /) → None#

实例化完成后自动初始化底层 OpenAI 客户端。

embed_documents(self, texts: List[str], **kwargs) → List[List[float]]#

批量生成多段文本的嵌入向量。

参数:

  • texts (List[str]) -- 待嵌入文本列表。

  • kwargs (Any) -- 额外推理参数，如 dimensions、user 等，将透传至底层 API。

返回:

与输入顺序对应的向量矩阵，每行维度由模型或 dimensions 字段决定。

返回类型:

List[List[float]]

embed_query(self, text: str, **kwargs) → List[float]#

生成单段文本的嵌入向量，内部调用 embed_documents 并返回第一条结果。

参数:

  • text (str) -- 待嵌入文本。

  • kwargs (Any) -- 额外推理参数，用法同 embed_documents。

返回:

长度为 ``dimensions``（或模型默认）的浮点向量。

返回类型:

List[float]

async aembed_query(self, text: str, **kwargs) → list[float]#

异步生成单段文本的嵌入向量。

参数:

  • text (str) -- 待嵌入的文本字符串。

  • kwargs (Any) -- 额外推理参数。

返回:

长度为 embedding_dim 的浮点向量。

返回类型:

list[float]

async aembed_documents(self, texts: list[str], **kwargs) → AsyncGenerator[list[list[float]], None]#

异步生成多段文本的嵌入向量列表。

参数:

  • texts (list[str]) -- 文本字符串列表。

  • kwargs (Any) -- 额外推理参数，如 chunk_size、retry 等。

返回:

与 texts 顺序对应的向量列表，每条向量长度为 embedding_dim。

返回类型:

list[list[float]]

class evofabric.core.clients.SentenceTransformerEmbed(EmbedClientBase)#

基于本地 Sentence-Transformer 模型的轻量级嵌入客户端，无需外部 API 即可生成高质量向量，适合离线、私有化及边缘部署场景。

参数:

  • model (str) -- 本地 Sentence-Transformer 模型名称或 HuggingFace Hub ID，例如 all-MiniLM-L6-v2。

  • device (str) -- 模型运行设备，默认为 "cpu"；可指定 "cuda"、"mps" 等以启用 GPU 加速。

model_post_init(self, context: Any, /) → None#

实例化完成后自动加载本地模型，设备与模型名由字段值注入。

embed_documents(self, texts: List[str], **kwargs) → List[List[float]]#

批量生成多段文本的嵌入向量。

参数:

  • texts (List[str]) -- 待嵌入文本列表。

  • kwargs (Any) -- 额外推理参数，如 batch_size、normalize_embeddings 等，将透传至底层模型。

返回:

与输入顺序对应的向量矩阵，每行维度由模型决定。

返回类型:

List[List[float]]

embed_query(self, text: str, **kwargs) → List[float]#

生成单段文本的嵌入向量，内部调用 embed_documents 并返回第一条结果。

参数:

  • text (str) -- 待嵌入文本。

  • kwargs (Any) -- 额外推理参数，用法同 embed_documents。

返回:

长度为模型输出维度的浮点向量。

返回类型:

List[float]

async aembed_query(self, text: str, **kwargs) → list[float]#

异步生成单段文本的嵌入向量。

参数:

  • text (str) -- 待嵌入的文本字符串。

  • kwargs (Any) -- 额外推理参数。

返回:

长度为 embedding_dim 的浮点向量。

返回类型:

list[float]

async aembed_documents(self, texts: list[str], **kwargs) → AsyncGenerator[list[list[float]], None]#

异步生成多段文本的嵌入向量列表。

参数:

  • texts (list[str]) -- 文本字符串列表。

  • kwargs (Any) -- 额外推理参数，如 chunk_size、retry 等。

返回:

与 texts 顺序对应的向量列表，每条向量长度为 embedding_dim。

返回类型:

list[list[float]]

Rerank Clients#

class evofabric.core.clients.RerankClientBase(BaseComponent)#

与任意后端重排序模型交互的基类客户端，用于对“查询-文本”对进行相关性重排并返回排序后的索引序列。

async rank(self, query: str, texts: List[str], **kwargs) → List[int]#

异步对查询与多条文本进行相关性重排序，返回按相关性从高到低排列的原始索引列表。

参数:

  • query (str) -- 查询字符串。

  • texts (List[str]) -- 待重排序的文本列表。

  • kwargs (Any) -- 其他推理参数，如 top_n、truncate、temperature 等，将透传至底层模型。

返回:

按相关性降序排列的原始文本索引列表，长度默认为 len(texts) 或 `top_n`（若指定）。

返回类型:

List[int]

class evofabric.core.clients.FlagRerankModel(RerankClientBase)#

基于 FlagEmbedding 的本地重排序模型实现，无需外部 API 即可对“查询-文本”对进行相关性打分与重排，适用于私有化及离线场景。

参数:

  • model (str) -- 本地 FlagRerank 模型名称或 HuggingFace Hub ID，例如 BAAI/bge-reranker-base。

  • top_n (int) -- 返回相关性最高的前 N 条索引，默认 1。

  • device (str) -- 模型运行设备，默认为 "cpu"；可指定 "cuda"、"cuda:0" 等以启用 GPU 加速。

model_post_init(self, context: Any, /) → None#

实例化完成后自动加载本地重排序模型，设备与模型名由字段值注入。

async rank(self, query: str, texts: List[str], **kwargs) → List[int]#

异步对查询与多条文本进行相关性重排序，返回按相关性降序排列的原始索引列表。

参数:

  • query (str) -- 查询字符串。

  • texts (List[str]) -- 待重排序的文本列表。

  • kwargs (Any) -- 额外推理参数，如 truncate、batch_size 等，将透传至底层模型。

返回:

长度不超过 top_n 的索引列表，按相关性从高到低排列。

返回类型:

List[int]

目录