agentscope.embedding

agentscope中的嵌入模块。

class EmbeddingModelBase

基础：object

嵌入模型的基类。

__init__(model_name)

初始化嵌入模型基类。

Parameters:

model_name (str) – 嵌入模型的名称。

Return type:

无

model_name: str

嵌入模型名称

async __call__(text, **kwargs)

使用给定的参数调用嵌入API.

Parameters:

• 文本 (列表[字符串])

• kwargs (Any) - 任意关键字参数

Return type:

嵌入响应

class EmbeddingUsage

基础类：DictMixin

嵌入模型API调用的用法。

time: float

以秒为单位表示的使用时间。

__init__(time, tokens=<factory>, type=<factory>)

Parameters:

• 时间 (浮点数)

• tokens (整数 | None)

• type (Literal['embedding'])

Return type:

无

tokens: int | None

如果可用，已使用的令牌数量。

type: Literal['embedding']

用法的类型，必须是 embedding。

class EmbeddingResponse

基类: DictMixin

嵌入响应类。

embeddings: List[List[float]]

嵌入数据

id: str

嵌入响应的标识

created_at: str

嵌入响应创建的时间戳

__init__(embeddings, id=<factory>, created_at=<factory>, type=<factory>, usage=<factory>, source=<factory>)

Parameters:

• embeddings (List[List[float]]) - 这是一个嵌入向量列表（浮点数列表的列表）

• id (字符串)

• created_at (str)

• type (Literal['embedding'])

• usage (EmbeddingUsage | None)

• source (Literal['cache', 'api'])

Return type:

无

type: Literal['embedding']

响应的类型，必须是embedding。

usage: EmbeddingUsage | None

如可用，嵌入模型API调用的使用方法。

source: Literal['cache', 'api']

如果响应来自缓存或API。

class DashScopeTextEmbedding

基类：EmbeddingModelBase

DashScope 文本嵌入模型类

__init__(api_key, model_name, embedding_cache=None)

初始化DashScope文本嵌入模型类。

Parameters:

• api_key (str) – 用于访问dashscope服务的API密钥。

• model_name (str) – 嵌入模型的名称。

• embedding_cache (EmbeddingCacheBase) – 嵌入缓存类实例，用于缓存嵌入结果以避免重复调用API。

Return type:

无

async __call__(text, **kwargs)

调用DashScope嵌入API接口。

Parameters:

• text (List[str]) – 需要被嵌入的输入文本。它可以是一个字符串列表。

• kwargs (Any)：可选关键字参数

Return type:

EmbeddingResponse

class OpenAITextEmbedding

Bases: EmbeddingModelBase

OpenAI 文本嵌入模型类。

__init__(api_key, model_name, embedding_cache=None, **kwargs)

初始化OpenAI文本嵌入模型类。

Parameters:

• api_key (str) – OpenAI API密钥。

• model_name (str) – 嵌入模型的名称。

• embedding_cache (EmbeddingCacheBase | None, 默认为 None) – 嵌入缓存类的实例，用于缓存嵌入结果以避免重复的API调用。

• kwargs (任何)

Return type:

无

async __call__(text, **kwargs)

调用OpenAI嵌入API。

Parameters:

• text (List[str]) – 待嵌入的输入文本。它可以是一个字符串列表。

• kwargs (任意)

Return type:

嵌入响应

class GeminiTextEmbedding

基类: EmbeddingModelBase

Gemini文本嵌入模型。

__init__(api_key, model_name, embedding_cache=None, **kwargs)

初始化Gemini文本嵌入模型类。

Parameters:

• api_key (str) – Gemini API 密钥。

• model_name (str) – 嵌入模型的名称。

• embedding_cache (EmbeddingCacheBase | None, 默认为 None) – 嵌入缓存类实例，用于缓存嵌入结果，避免重复的 API 调用。

• kwargs (任意类型)

Return type:

无

async __call__(text, **kwargs)

Gemini 嵌入 API 调用。

Parameters:

• text (List[str]) – 需要被嵌入的输入文本。它可以是一个字符串列表。

• kwargs (任意)

Return type:

嵌入响应

class OllamaTextEmbedding

基类：EmbeddingModelBase

Ollama 嵌入模型。

__init__(model_name, host=None, embedding_cache=None, **kwargs)

初始化Ollama文本嵌入模型类。

Parameters:

• model_name (str) - 嵌入模型的名称。

• host (str | None, defaults to None) – Ollama API 的主机 URL 地址。

• embedding_cache (EmbeddingCacheBase | None, 默认为 None) – 嵌入缓存类的实例，用于缓存嵌入结果以避免重复的API调用。

• kwargs (任意类型)

Return type:

无

async __call__(text, **kwargs)

调用Ollama嵌入API。

Parameters:

• text (List[str]) – 待嵌入的输入文本。可以是字符串列表。

• kwargs (任意类型)

Return type:

嵌入响应

class EmbeddingCacheBase

基础：object

用于嵌入缓存的基础类，其负责存储和获取嵌入结果。

abstract async store(embeddings, identifier, overwrite=False, **kwargs)

以给定标识符存储嵌入内容。

Parameters:

• embeddings (List[Embedding]) – 要存储的嵌入向量。

• identifier (JSONSerializableObject) – 用于区分嵌入向量的标识符。

• overwrite (bool, 默认为 False) – 是否覆盖具有相同标识符的现有嵌入向量。如果为 True，则现有嵌入将被替换。

• kwargs (Any)：可选关键字参数

Return type:

无

abstract async retrieve(identifier)

获取给定标识符对应的嵌入向量。如果未找到，则返回 None。

Parameters:

identifier (JSONSerializableObject) – 用于检索嵌入向量的标识符.

Return type:

列表[列表[浮点数]] | 无

abstract async remove(identifier)

移除具有给定标识符的嵌入向量。

Parameters:

identifier (JSONSerializableObject) – 要移除嵌入的标识符。

Return type:

无

abstract async clear()

清除所有缓存的嵌入向量。

Return type:

无

class FileEmbeddingCache

Bases: EmbeddingCacheBase

存储每个嵌入向量到二进制文件中的嵌入缓存类。

__init__(cache_dir='./.cache/embeddings', max_file_number=None, max_cache_size=None)

初始化文件嵌入缓存类。

Parameters:

• cache_dir (str, 默认为 “./.cache/embeddings”) – 存储嵌入文件的目录。

• max_file_number (int | None, 默认为 None) – 缓存目录中保留的最大文件数量。如果超过此数量，将删除最旧的文件。

• max_cache_size (int | None, 默认为 None) – 缓存目录的最大大小（以MB为单位）。如果超过此限制，将删除最旧的文件，直到大小回到限制范围内。

Return type:

无

property cache_dir: str

嵌入文件存储的缓存目录。

async store(embeddings, identifier, overwrite=False, **kwargs)

使用给定标识符存储嵌入向量。

Parameters:

• embeddings (List[Embedding]) – 需要存储的嵌入向量。

• identifier (JSONSerializableObject) – 用于区分嵌入的唯一标识符，该标识符将用于生成可哈希的文件名，因此它应当是JSON可序列化的（例如字符串、数字、列表、字典）。

• overwrite (bool, 默认为 False) – 是否覆盖具有相同标识符的已有嵌入。如果为 True，则现有嵌入将被替换。

• kwargs (Any)：可选关键字参数

Return type:

无

async retrieve(identifier)

根据给定的标识符检索嵌入向量。如果未找到， 则返回 None。

Parameters:

identifier (JSONSerializableObject) – 用于检索嵌入向量的标识符，该标识符将 用于生成可哈希的文件名，因此它应该是 可 JSON 序列化的（例如字符串、数字、列表、字典）。

Return type:

列表[列表[浮点数]] | 无

async remove(identifier)

根据给定标识符移除嵌入向量。

Parameters:

identifier (JSONSerializableObject) – 要移除嵌入的标识符，它将被用于生成一个可哈希的文件名，所以应该是可JSON序列化的（例如，一个字符串、数字、列表、字典）。

Return type:

无

async clear()

通过移除所有文件来清空缓存目录。

Return type:

无