agentscope.embedding

The embedding module in agentscope.

class EmbeddingModelBase

基类：object

Base class for embedding models.

supported_modalities: list[str]

The supported data modalities, e.g. "text", "image", "video".

__init__(model_name, dimensions)

Initialize the embedding model base class.

参数:

• model_name (str) -- The name of the embedding model.

• dimensions (int) -- The dimension of the embedding vector.

返回类型:

None

model_name: str

The embedding model name

dimensions: int

The dimensions of the embedding vector.

async __call__(*args, **kwargs)

Call the embedding API with the given arguments.

参数:

• args (Any)

• kwargs (Any)

返回类型:

EmbeddingResponse

class EmbeddingUsage

基类：DictMixin

The usage of an embedding model API invocation.

time: float

The time used in seconds.

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

参数:

• time (float)

• tokens (int | None)

• type (Literal['embedding'])

返回类型:

None

tokens: int | None

The number of tokens used, if available.

type: Literal['embedding']

The type of the usage, must be embedding.

class EmbeddingResponse

基类：DictMixin

The embedding response class.

embeddings: List[List[float]]

The embedding data

id: str

The identity of the embedding response

created_at: str

The timestamp of the embedding response creation

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

参数:

• embeddings (List[List[float]])

• id (str)

• created_at (str)

• type (Literal['embedding'])

• usage (EmbeddingUsage | None)

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

返回类型:

None

type: Literal['embedding']

The type of the response, must be embedding.

usage: EmbeddingUsage | None

The usage of the embedding model API invocation, if available.

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

If the response comes from the cache or the API.

class DashScopeTextEmbedding

基类：EmbeddingModelBase

DashScope text embedding API class.

备注

From the `official documentation

<https://bailian.console.aliyun.com/?tab=api#/api/?type=model&url=2712515>`_:

• The max batch size that DashScope text embedding API

supports is 10 for text-embedding-v4 and text-embedding-v3 models, and 25 for text-embedding-v2 and text-embedding-v1 models. - The max token limit for a single input is 8192 tokens for v4 and v3 models, and 2048 tokens for v2 and v1 models.

supported_modalities: list[str] = ['text']

This class only supports text input.

__init__(api_key, model_name, dimensions=1024, embedding_cache=None)

Initialize the DashScope text embedding model class.

参数:

• api_key (str) -- The dashscope API key.

• model_name (str) -- The name of the embedding model.

• dimensions (int, defaults to 1024) -- The dimension of the embedding vector, refer to the official documentation for more details.

• embedding_cache (EmbeddingCacheBase) -- The embedding cache class instance, used to cache the embedding results to avoid repeated API calls.

返回类型:

None

async __call__(text, **kwargs)

Call the DashScope embedding API.

参数:

• text (List[str | TextBlock]) -- The input text to be embedded. It can be a list of strings.

• kwargs (Any)

返回类型:

EmbeddingResponse

class DashScopeMultiModalEmbedding

基类：EmbeddingModelBase

The DashScope multimodal embedding API, supporting text, image and video embedding.

supported_modalities: list[str] = ['text', 'image', 'video']

This class supports text, image and video input.

__init__(api_key, model_name, dimensions=None, embedding_cache=None)

Initialize the DashScope multimodal embedding model class.

参数:

• api_key (str) -- The dashscope API key.

• model_name (str) -- The name of the embedding model, e.g. "multimodal-embedding- v1", "tongyi-embedding-vision-plus".

• dimensions (int, defaults to 1024) --

  The dimension of the embedding vector, refer to the official documentation for more details.

• embedding_cache (EmbeddingCacheBase) -- The embedding cache class instance, used to cache the embedding results to avoid repeated API calls.

返回类型:

None

async __call__(inputs, **kwargs)

Call the DashScope multimodal embedding API, which accepts text, image, and video data.

参数:

• inputs (list[TextBlock | ImageBlock | VideoBlock]) -- The input data to be embedded. It can be a list of text, image, and video blocks.

• kwargs (Any)

返回:

The embedding response object, which contains the embeddings and usage information.

返回类型:

EmbeddingResponse

class OpenAITextEmbedding

基类：EmbeddingModelBase

OpenAI text embedding model class.

supported_modalities: list[str] = ['text']

This class only supports text input.

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

Initialize the OpenAI text embedding model class.

参数:

• api_key (str) -- The OpenAI API key.

• model_name (str) -- The name of the embedding model.

• dimensions (int, defaults to 1024) -- The dimension of the embedding vector.

• embedding_cache (EmbeddingCacheBase | None, defaults to None) -- The embedding cache class instance, used to cache the embedding results to avoid repeated API calls.

• kwargs (Any)

返回类型:

None

# TODO: handle batch size limit and token limit

async __call__(text, **kwargs)

Call the OpenAI embedding API.

参数:

• text (List[str | TextBlock]) -- The input text to be embedded. It can be a list of strings.

• kwargs (Any)

返回类型:

EmbeddingResponse

class GeminiTextEmbedding

基类：EmbeddingModelBase

The Gemini text embedding model.

supported_modalities: list[str] = ['text']

This class only supports text input.

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

Initialize the Gemini text embedding model class.

参数:

• api_key (str) -- The Gemini API key.

• model_name (str) -- The name of the embedding model.

• dimensions (int, defaults to 3072) --

  The dimension of the embedding vector, refer to the official documentation for more details.

• embedding_cache (EmbeddingCacheBase | None, defaults to None) -- The embedding cache class instance, used to cache the embedding results to avoid repeated API calls.

• kwargs (Any)

返回类型:

None

async __call__(text, **kwargs)

The Gemini embedding API call.

参数:

• text (List[str | TextBlock]) -- The input text to be embedded. It can be a list of strings.

• kwargs (Any)

返回类型:

EmbeddingResponse

# TODO: handle the batch size limit

class OllamaTextEmbedding

基类：EmbeddingModelBase

The Ollama embedding model.

supported_modalities: list[str] = ['text']

This class only supports text input.

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

Initialize the Ollama text embedding model class.

参数:

• model_name (str) -- The name of the embedding model.

• dimensions (int) -- The dimension of the embedding vector, the parameter should be provided according to the model used.

• host (str | None, defaults to None) -- The host URL for the Ollama API.

• embedding_cache (EmbeddingCacheBase | None, defaults to None) -- The embedding cache class instance, used to cache the embedding results to avoid repeated API calls.

• kwargs (Any)

返回类型:

None

async __call__(text, **kwargs)

Call the Ollama embedding API.

参数:

• text (List[str | TextBlock]) -- The input text to be embedded. It can be a list of strings.

• kwargs (Any)

返回类型:

EmbeddingResponse

class EmbeddingCacheBase

基类：object

Base class for embedding caches, which is responsible for storing and retrieving embeddings.

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

Store the embeddings with the given identifier.

参数:

• embeddings (List[Embedding]) -- The embeddings to store.

• identifier (JSONSerializableObject) -- The identifier to distinguish the embeddings.

• overwrite (bool, defaults to False) -- Whether to overwrite existing embeddings with the same identifier. If True, existing embeddings will be replaced.

• kwargs (Any)

返回类型:

None

abstract async retrieve(identifier)

Retrieve the embeddings with the given identifier. If not found, return None.

参数:

identifier (JSONSerializableObject) -- The identifier to retrieve the embeddings.

返回类型:

List[List[float]] | None

abstract async remove(identifier)

Remove the embeddings with the given identifier.

参数:

identifier (JSONSerializableObject) -- The identifier to remove the embeddings.

返回类型:

None

abstract async clear()

Clear all cached embeddings.

返回类型:

None

class FileEmbeddingCache

基类：EmbeddingCacheBase

The embedding cache class that stores each embeddings vector in binary files.

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

Initialize the file embedding cache class.

参数:

• cache_dir (str, defaults to "./.cache/embeddings") -- The directory to store the embedding files.

• max_file_number (int | None, defaults to None) -- The maximum number of files to keep in the cache directory. If exceeded, the oldest files will be removed.

• max_cache_size (int | None, defaults to None) -- The maximum size of the cache directory in MB. If exceeded, the oldest files will be removed until the size is within the limit.

返回类型:

None

property cache_dir: str

The cache directory where the embedding files are stored.

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

Store the embeddings with the given identifier.

参数:

• embeddings (List[Embedding]) -- The embeddings to store.

• identifier (JSONSerializableObject) -- The identifier to distinguish the embeddings, which will be used to generate a hashable filename, so it should be JSON serializable (e.g. a string, number, list, dict).

• overwrite (bool, defaults to False) -- Whether to overwrite existing embeddings with the same identifier. If True, existing embeddings will be replaced.

• kwargs (Any)

返回类型:

None

async retrieve(identifier)

Retrieve the embeddings with the given identifier. If not found, return None.

参数:

identifier (JSONSerializableObject) -- The identifier to retrieve the embeddings, which will be used to generate a hashable filename, so it should be JSON serializable (e.g. a string, number, list, dict).

返回类型:

List[List[float]] | None

async remove(identifier)

Remove the embeddings with the given identifier.

参数:

identifier (JSONSerializableObject) -- The identifiers to remove the embeddings, which will be used to generate a hashable filename, so it should be JSON serializable (e.g. a string, number, list, dict).

返回类型:

None

async clear()

Clear the cache directory by removing all files.

返回类型:

None