LLM、嵌入器和重新排序器

本页介绍用于将 LLM、嵌入程序和重新排列到 Oracle Agent Memory 中的抽象接口。

LLM 接口

class `oracleagentmemory.apis.llms.ILlm`

基础：ABC

LLM 调用的抽象接口。

method `generate`（抽象）

同步从 LLM 生成响应。

参数：
- prompt str | Sequence[Message | Mapping[str, str | Sequence[Mapping[str, Any]]]] | ChatMessageTypedDictT- 字符串、聊天样式的字典序列或 Message 对象的序列。字符串将成为用户消息；消息内容可能包括文本和图像部分。图像部分在发送到提供程序之前进行验证。
- response_json_schema dict[str, Any] | None- 描述预期响应格式的可选 JSON 方案。
- **kwargs ( Any )- 其他调用选项。内置 Llm 接受 api_type=LlmApiType.RESPONSES 以选择响应 API，接受 image_input_limit_config=ImageInputLimitConfig(...) 以覆盖该请求的图像限制。其他关键字参数将转发到底层后端。
返回值：标准化 LLM 输出。
返回类型：LlmResponse

method `generate_async`（抽象、异步）

从 LLM 异步生成响应。

参数：
- prompt str | Sequence[Message | Mapping[str, str | Sequence[Mapping[str, Any]]]] | ChatMessageTypedDictT- 字符串、聊天样式的字典序列或 Message 对象的序列。字符串将成为用户消息；消息内容可能包括文本和图像部分。图像部分在发送到提供程序之前进行验证。
- response_json_schema dict[str, Any] | None- 描述预期响应格式的可选 JSON 方案。
- **kwargs ( Any )- 其他调用选项。内置 Llm 接受 api_type=LlmApiType.RESPONSES 以选择响应 API，接受 image_input_limit_config=ImageInputLimitConfig(...) 以覆盖该请求的图像限制。其他关键字参数将转发到底层后端。
返回值：标准化 LLM 输出。
返回类型：LlmResponse

LLM 响应

class `oracleagentmemory.apis.llms.LlmResponse`

基准：object

ILlm 返回的小型规范化响应。

参数：文本 str

文本

生成的主要文本内容。

类型： str

嵌入器界面

class `oracleagentmemory.apis.IEmbedder`

基础：ABC

文本嵌入程序的抽象界面。

method `embed`（抽象）

将一批文本嵌入 2D float32 NumPy 数组中。

参数：
- texts list[str]- 要嵌入的一批文本。
- is_query bool- 是否嵌入批处理以进行查询时间检索。
返回值：使用 dtype=float32 形成 (len(texts), dim) 的 2D 数组。
返回类型： numpy.ndarray

method `embed_async`（抽象、异步）

将一批文本嵌入 2D float32 NumPy 数组中。

参数：
- texts list[str]- 要嵌入的一批文本。
- is_query bool- 是否嵌入批处理以进行查询时间检索。
返回值：使用 dtype=float32 形成 (len(texts), dim) 的 2D 数组。
返回类型： numpy.ndarray

property（属性）`embedding_dimension`

返回类型： int
说明：返回此嵌入程序生成的嵌入的大小。

从配置或提供程序元数据中知道嵌入宽度时，子类可以覆盖此属性。缺省实现探测 embed() 一次并缓存结果大小。

返回值：每个嵌入向量中浮点值的正数。
返回类型： int

property（属性）`max_input_tokens`

返回类型： int
说明：返回支持的最大输入标记数。

从配置或提供程序元数据中知道模型的输入预算时，子类可以覆盖此属性。默认实现将验证大小为估计 512 输入令牌的探测器一次，并将 512 高速缓存为保守回退。它不会在本地运行模型标记器，因此当已知模型的实际输入预算时，调用者应该手动设置 max_input_tokens。

返回值：一个文本有效负载的实际最大输入标记计数。
返回类型： int

重新分级界面

class `oracleagentmemory.apis.IReranker`

基础：ABC

用于同步和异步文档重新排序的抽象接口。

实现必须为每个输入文档返回一个结果。每个基于零的输入索引必须只出现一次。relevance_score 必须是有限的，分数越高，相关性越高。结果必须从最高分到最低分进行排序。

method `rerank`

通过委托给 rerank_async 同步对文档进行排名。

参数：
- query str- 用于比较文档的搜索查询。
- documents（文档）list[str]- 以稳定的输入顺序候选文档文本。结果索引指此列表中的职位。
- **kwargs ( Any )- 特定于提供程序的选项。
返回值：完整排名，仅显示 len(documents) 个结果。每个输入索引出现一次，从最相关到最不相关排序。
返回类型：RerankResponse

method `rerank_async`（抽象、异步）

按与查询的相关性对文档进行异步排序。

参数：
- query str- 用于比较文档的搜索查询。
- documents（文档）list[str]- 以稳定的输入顺序候选文档文本。结果索引指此列表中的职位。
- **kwargs ( Any )- 特定于提供程序的选项。
返回值：完整排名，仅显示 len(documents) 个结果。每个输入索引出现一次，从最相关到最不相关排序。
返回类型：RerankResponse

class `oracleagentmemory.apis.RerankResponse`

基准：object

按相关性评分降序排列的完整文档排名。

参数：结果 list[RerankResponseResult]

class `oracleagentmemory.apis.RerankResponseResult`

基准：object

一个文档的重排结果。

参数：
- index int- 输入列表中文档的零基位置。
- relevance_score float- 查询文档对的相关性得分。更高的价值意味着更高的相关性。
- document（文档）str | None- 提供程序返回时的文档文本，否则为 None。

LiteLLM 适配器

class `oracleagentmemory.core.llms.LlmApiType`

基础：str、Enum

Llm 支持 OpenAI 兼容的 API 系列。

CHAT_COMPLETIONS = ‘ CHAT_COMPLETIONS ’

响应 = 'RESPONSES'

class `oracleagentmemory.core.llms.Llm`

基础：ILlm

用于生成模型响应的适配器。

创建 LLM 适配器。

参数：
- model str- 发送到底层模型提供者的模型标识符。
- api_base str | None- 与 OpenAI 兼容的端点的可选基本 URL。
- api_key str | None- 联系提供程序时使用的可选 API 密钥。
- api_type LlmApiType- 要调用的 API 系列。将 LlmApiType.CHAT_COMPLETIONS 用于聊天完成，将 LlmApiType.RESPONSES 用于响应 API。默认值为 LlmApiType.CHAT_COMPLETIONS。
- stream bool- 是否请求流输出。流在内部使用，并以单个 LlmResponse 形式返回。
- temperature float | None- 可选的采样温度。
- max_tokens int | None- 可选输出令牌限制。使用 api_type=LlmApiType.CHAT_COMPLETIONS 时，此消息将作为 max_tokens 发送。
- reasoning_effort str | None- 可选推理工作。使用 api_type=LlmApiType.CHAT_COMPLETIONS 时，此消息将作为 reasoning_effort 发送。使用 api_type=LlmApiType.RESPONSES 时，将转换为 reasoning={"effort": ...}。
- enable_structured_output_reminder bool- 在请求结构化输出时是否将结构化输出方案附加到提示。如果省略，则缺省值遵循模型路由：它为 LiteLLM 显式 "openai/..." 路由上的托管 vLLM 和非封闭模型启用。为裸模型名称或其他定制端点显式设置此项。
- supports_vision bool- 此模型是否接受生成提示中的图像内容。如果省略，则会延迟检测支持：适配器首先检查模型元数据，当元数据不可用时，会发送固定的红色图像探测器。将此参数设置为 True 或 False 以跳过检测。
- image_input_limit_config ImageInputLimitConfig- 可选的原始映像和每请求映像限制。省略的字段使用 SDK 默认值。对每个映像请求仍启用验证。
- max_concurrent_requests int | None- 此 LLM 实例允许的最大异步请求数。省略该值以使用 16。传递 None 以禁用并发限制。当端点需要不同的行为时显式设置此项。
- proxy str | None- 提供程序请求的可选代理 URL。如果提供，则此显式代理优先于环境中的代理设置。如果省略，则启用 trust_env 时将使用环境代理设置。
- trust_env bool- 提供者是否请求从环境变量读取代理和 TLS 设置。省略时默认为 True。设置为 False 可忽略这些环境设置；仍使用显式 proxy。
- key_file str | None- 以 PEM 格式指向客户机私钥文件的可选路径。当服务器需要双向 TLS 时，将其与 cert_file 一起提供。
- cert_file str | None- 以 PEM 格式指向客户机证书链文件的可选路径。当服务器需要双向 TLS 时，将其与 key_file 一起提供。
- ca_file str | None- 用于验证服务器证书的 PEM 格式的可信 CA 证书或包的可选路径。用于专用或非系统 CA。
- **default_kwargs ( Any )- 应用于每个调用的高级缺省关键字参数。对于通用连接和生成设置，首选上述显式参数。在 default_kwargs 中显式提供同一设置时，显式参数优先。

示例

OCI Generative AI 模型使用 LiteLLM 的 "oci/..." 模型标识符。一种常见的设置是将 OCI API 密钥验证详细信息从标准 OCI 配置文件传递到特定于 LiteLLM 的关键字参数。此程序包未安装 OCI Python SDK；已经依赖它的应用程序也可以传递 oci_signer 对象。

import configparser
from pathlib import Path
parser = configparser.RawConfigParser()
parser.read(Path("~/.oci/config").expanduser())
cfg = parser["DEFAULT"]
key_file = Path(cfg["key_file"]).expanduser()
oci_llm = Llm(
    model="oci/openai.gpt-oss-120b",
    oci_compartment_id="ocid1.compartment.oc1..example",
    oci_region=cfg.get("region", "us-chicago-1"),
    oci_user=cfg["user"],
    oci_fingerprint=cfg["fingerprint"],
    oci_tenancy=cfg["tenancy"],
    oci_key_file=str(key_file),
)
oci_llm.generate("Reply with OK.")

OpenAI 托管的模型使用 LiteLLM 模型标识符，例如 "openai/gpt-5.1" 和 OpenAI API 密钥。聊天完成是默认 API 系列。

openai_llm = Llm(
    model="openai/gpt-5.1",
    api_key="sk-example",
    temperature=0,
    max_tokens=128,
)
openai_llm.model
'openai/gpt-5.1'
openai_llm.generate("Reply with OK.")

当应通过 OpenAI 响应 API 而不是聊天完成来调用目标模型时，请使用 api_type=LlmApiType.RESPONSES。

responses_llm = Llm(
    model="openai/gpt-5.4",
    api_key="sk-example",
    api_type=LlmApiType.RESPONSES,
    reasoning_effort="high",
    stream=True,
)
responses_llm.model
'openai/gpt-5.4'

与 OpenAI 兼容的自托管服务器（包括 vLLM）通过 "openai/..." 模型标识符和服务器的 /v1 基本 URL 来调用。当端点不强制验证时，传递名义 api_key，例如 "none"。

vllm_llm = Llm(
    model="openai/openai/gpt-oss-120b",
    api_base="http://localhost:8000/v1",
    api_key="none",
    stream=True,
)
vllm_llm.model
'openai/openai/gpt-oss-120b'
vllm_llm.generate("Reply with OK.")

method `generate`

生成回应。

参数：
- prompt str | Sequence[Message | Mapping[str, str | Sequence[Mapping[str, Any]]]] | ChatMessageTypedDictT- 字符串、聊天样式的字典序列或消息对象的序列。字符串将成为用户消息；内容可能包括文本和图像部分。图像部分在发送到提供程序之前进行验证。
- response_json_schema dict[str, Any] | None- 描述预期响应格式的可选 JSON 方案。如果提供，此方法将通过与 OpenAI 兼容的 response_format 使用提供程序本机结构化输出机制。
- **kwargs ( Any )- 其他调用参数。通过 api_type=LlmApiType.RESPONSES 通过 Responses API 传送此调用。对于映像提示，传递 image_input_limit_config=ImageInputLimitConfig(...) 以覆盖此 Llm 实例对此请求的映像限制；省略的字段将继承实例配置。其他关键字参数随提供程序请求一起发送。
返回值：标准化 LLM 输出。
返回类型：LlmResponse

method `generate_async`（异步）

异步生成响应。

参数：
- prompt str | Sequence[Message | Mapping[str, str | Sequence[Mapping[str, Any]]]] | ChatMessageTypedDictT- 字符串、提示或聊天式消息序列。字符串将成为用户消息；内容可能包括文本和图像部分。图像部分在发送到提供程序之前进行验证。
- response_json_schema dict[str, Any] | None- 描述预期响应格式的可选 JSON 方案。如果提供，此方法将通过与 OpenAI 兼容的 response_format 使用提供程序本机结构化输出机制。
- **kwargs ( Any )- 其他调用参数。通过 api_type=LlmApiType.RESPONSES 通过 Responses API 传送此调用。对于映像提示，传递 image_input_limit_config=ImageInputLimitConfig(...) 以覆盖此 Llm 实例对此请求的映像限制；省略的字段将继承实例配置。其他关键字参数随提供程序请求一起发送。
返回值：标准化 LLM 输出。
返回类型：LlmResponse

property（属性）`supports_vision`

返回类型： bool
说明：返回此 LLM 是否支持图像输入，并延迟检测。

class `oracleagentmemory.core.embedders.Embedder`

基础：IEmbedder

提供商支持的嵌入程序。

创建提供程序支持的嵌入程序。

参数：
- model str- 发送到底层嵌入提供程序的模型标识符。
- api_base str | None- 与 OpenAI 兼容的端点的可选基本 URL。
- api_key str | None- 联系提供程序时使用的可选 API 密钥。
- embedding_dimension int | None- 可选嵌入向量维。如果提供，则数据库支持的客户端可以创建或验证向量方案，而无需发送提供程序探测。省略时，embedding_dimension 会使用小回退探测器延迟推断维。
- max_input_tokens int- 嵌入模型支持的最大输入令牌计数。如果省略，max_input_tokens 属性将验证大小为估计 512 输入令牌的提供程序探测器，并将 512 高速缓存为保守回退。它不会在本地运行模型标记器，因此请根据模型记录的输入预算手动设置 max_input_tokens。
- normalize bool- 是否对提供者返回的嵌入进行 L2 规范化。
- query_prefix str | None- 仅在嵌入查询文本时添加可选前缀。
- document_prefix str | None- 仅当嵌入非查询文本时才添加可选前缀。
- truncate_prompt_tokens int | None- 转发给支持截断长嵌入提示的提供者的可选输入令牌限制。
- proxy str | None- 提供程序请求的可选代理 URL。如果提供，则此显式代理优先于环境中的代理设置。如果省略，则启用 trust_env 时将使用环境代理设置。
- trust_env bool- 提供者是否请求从环境变量读取代理和 TLS 设置。省略时默认为 True。设置为 False 可忽略这些环境设置；仍使用显式 proxy。
- key_file str | None- 以 PEM 格式指向客户机私钥文件的可选路径。当服务器需要双向 TLS 时，将其与 cert_file 一起提供。
- cert_file str | None- 以 PEM 格式指向客户机证书链文件的可选路径。当服务器需要双向 TLS 时，将其与 key_file 一起提供。
- ca_file str | None- 用于验证服务器证书的 PEM 格式的可信 CA 证书或包的可选路径。用于专用或非系统 CA。
- **default_kwargs ( Any )- 应用于每个嵌入调用的高级缺省关键字参数。对于通用设置，首选以上显式参数。

示例

OCI Generative AI 嵌入模型使用 "oci/..." 模型标识符。一种常见的设置是将 OCI API 密钥验证详细信息从标准 OCI 配置文件传递到特定于 LiteLLM 的关键字参数。此程序包未安装 OCI Python SDK；已经依赖它的应用程序也可以传递 oci_signer 对象。

import configparser
from pathlib import Path
parser = configparser.RawConfigParser()
parser.read(Path("~/.oci/config").expanduser())
cfg = parser["DEFAULT"]
key_file = Path(cfg["key_file"]).expanduser()
oci_embedder = Embedder(
    model="oci/cohere.embed-english-v3.0",
    oci_compartment_id="ocid1.compartment.oc1..example",
    oci_region=cfg.get("region", "us-chicago-1"),
    oci_user=cfg["user"],
    oci_fingerprint=cfg["fingerprint"],
    oci_tenancy=cfg["tenancy"],
    oci_key_file=str(key_file),
)
oci_embedder.embed(["hello world"])

OpenAI 托管的嵌入模型使用标识符，例如带有 OpenAI API 密钥的 "openai/text-embedding-3-small"。

openai_embedder = Embedder(
    model="openai/text-embedding-3-small",
    api_key="sk-example",
    truncate_prompt_tokens=8192,
)
openai_embedder.model
'openai/text-embedding-3-small'
openai_embedder.embed(["hello world"])

与 OpenAI 兼容的自托管嵌入式服务器（包括 vLLM）使用服务器 /v1 基本 URL 的 "hosted_vllm/..." 提供程序前缀。

vllm_embedder = Embedder(
    model="hosted_vllm/sentence-transformers/all-MiniLM-L6-v2",
    api_base="http://localhost:8000/v1",
)
vllm_embedder.model
'hosted_vllm/sentence-transformers/all-MiniLM-L6-v2'
vllm_embedder.embed(["hello world"])

method `embed`

使用配置的提供程序嵌入一批文本。

参数：
- texts list[str]- 要嵌入的一批原始文本字符串。
- is_query bool- 文本是否为查询。查询文本接收 query_prefix，非查询文本在配置时接收 document_prefix。
返回值：提供方返回的嵌入向量的二维 float32 矩阵。
返回类型： numpy.ndarray
引发：RuntimeError - 如果提供程序响应有效负载不包括嵌入数据。

method `embed_async`（异步）

使用配置的提供程序异步嵌入一批文本。

参数：
- texts list[str]- 要嵌入的一批原始文本字符串。
- is_query bool- 文本是否为查询。查询文本接收 query_prefix，非查询文本在配置时接收 document_prefix。
返回值：提供方返回的嵌入向量的二维 float32 矩阵。
返回类型： numpy.ndarray
引发：RuntimeError - 如果提供程序响应有效负载不包括嵌入数据。

property（属性）`embedding_dimension`

返回类型： int
说明：返回已配置或推断的嵌入维。
返回值：每个嵌入向量中维数的正数。
返回类型： int

注释

返回构造器提供的值，而不与提供程序联系。否则，属性将探测一次并缓存结果。

property（属性）`max_input_tokens`

返回类型： int
说明：返回已配置或推断的嵌入输入令牌限制。
返回值：一个文本有效负载的实际最大输入标记计数。
返回类型： int

注释

返回构造器提供的值，而不与提供程序联系。否则，该属性将验证大小为估计 512 输入令牌的提供程序探测器，并将 512 高速缓存为保守回退。它不会在本地运行模型标记器，因此当精度很重要时，请从模型的已记录输入预算中手动设置 max_input_tokens。

class `oracleagentmemory.core.Reranker`

基础：IReranker

由提供方中立的重新排列接口支持的重新排列。

参数：
- model str- 重新排序模型标识符。为 OCI Generative AI 模型添加前缀 oci/，例如 oci/cohere.rerank-v4.0-fast。
- api_base str | None- 与 OpenAI 兼容的重排端点的可选基本 URL。
- api_key str | None- 提供者使用的可选 API 密钥。
- **default_kwargs ( Any )-
  
  应用于每个重新排序请求的特定于提供商的选项。
  
  注： OCI 重排需要 oci_compartment_id、oci_region、oci_user、oci_fingerprint、oci_tenancy 和 oci_key_file。在使用 OCI 模型之前安装可选的 rerank-oci 相关项组。

示例

reranker = Reranker(
    model="your-reranker-model",
    api_base="https://your-reranker-endpoint/v1",
    api_key="your-api-key",
)
reranker.rerank("favorite food", ["The user likes pasta."])

oci_reranker = Reranker(
    model="oci/cohere.rerank-v4.0-fast",
    oci_compartment_id="ocid1.compartment...",
    oci_region="your-region",
    oci_user="ocid1.user...",
    oci_fingerprint="aa:bb:cc",
    oci_tenancy="ocid1.tenancy...",
    oci_key_file="~/.oci/oci_api_key.pem",
)
oci_reranker.rerank("favorite food", ["The user likes pasta."])

创建由提供程序支持的重新排序器。

method `rerank_async`（异步）

按与查询的相关性对文档进行异步排序。

参数：
- query str- 用于比较文档的搜索查询。
- documents（文档）list[str]- 以稳定的输入顺序候选文档文本。
- **kwargs （任何）- 特定于提供程序的选项，转发给重新排序的提供方。
退货：从最高相关性评分到最低的完整供应商排名。
返回类型：RerankResponse

Oracle DB 嵌入程序

class `oracleagentmemory.core.embedders.OracleDBEmbedder`

基础：IEmbedder

通过调用 Oracle AI Database 嵌入 SQL 来嵌入文本。

此嵌入程序使程序包的现有嵌入程序合同保持不变，同时通过 SQL 将嵌入生成委托给数据库。对于数据库驻留模型配置，直接嵌入优先于 VECTOR_EMBEDDING，当向量器配置需要 JSON 提供方参数表面时，可回退到 DBMS_VECTOR_CHAIN.UTL_TO_EMBEDDING。

创建由 Oracle AI Database SQL 执行支持的嵌入程序。

参数：
- connection object- 具有可调用的 cursor() 或 acquire() 方法的 Oracle DB 连接或类似池的对象。
- model str- 模型标识符。对于默认 "database" 提供程序，这必须是数据库内嵌入模型的未加引号的 Oracle SQL 标识符或方案限定标识符。连接的方案必须能够解析 SQL 中的此模型名称。对于远程提供程序，请使用该服务所需的模型名称或特定于提供程序的模型标识符。
- input_name str- 向量器配置针对数据库驻留的模型时 VECTOR_EMBEDDING 使用的模型输入名称。默认为 "DATA"，这是 Oracle 的 DBMS_VECTOR ONNX 嵌入模型示例和元数据使用的输入名称。如果导入的模型使用不同的属性，请在此处传递实际模型输入名称。
- embedding_dimension int | None- 可选嵌入向量维。如果提供，则由数据库支持的客户机可以创建或验证向量方案，而无需发送维探测查询。省略时，将通过一个探测嵌入请求延迟推断维。
- max_input_tokens int- 默认存储块使用的最大输入令牌预算。如果省略，max_input_tokens 属性将验证大小约为 512 输入令牌的数据库模型探测器，并将 512 高速缓存为保守回退。它不会在本地运行模型标记器，因此请根据模型记录的输入预算手动设置 max_input_tokens。
- normalize bool- 是否在从数据库中提取嵌入 L2 规范化。
- query_prefix str | None- 仅在嵌入查询文本时添加可选前缀。
- batch_size int- 分组到一个 SQL 嵌入往返中的最大文本数。
- provider str- 嵌入在 Oracle AI Database 中配置的提供程序。默认值 "database" 使用加载到 Oracle Database 中的嵌入模型，通常采用 ONNX 格式。远程提供商包括 Cohere、OpenAI、Google AI 和 Oracle Cloud Infrastructure Generative AI 等服务。与 OpenAI 兼容的服务（例如 vLLM）使用 "openai" 以及 provider_options 中的服务端点。有关受支持的提供程序及其配置，请参见 Oracle 的 DBMS_VECTOR_CHAIN 文档：https://docs.oracle.com/en/database/oracle/oracle-database/26/vecse/dbms_vector_chain-vecse.html
- provider_options Mapping[str, Any] | None- 可选的 Oracle 向量器设置，例如 url、credential_name 或 host="local"。构造器参数将覆盖此映射中的 provider、model 和 input_name。Oracle 文档提供程序选项以及如何创建数据库身份证明，网址为：https://docs.oracle.com/en/database/oracle/oracle-database/26/vecse/utl_to_embedding-and-utl_to_embeddings-dbms_vector_chain.html https://docs.oracle.com/en/database/oracle/oracle-database/26/vecse/create_credential-dbms_vector_chain.html

示例

使用 Oracle 连接池和驻留在数据库中的嵌入模型：

import oracledb
pool = oracledb.create_pool(
    user="scott",
    password="tiger",
    dsn="dbhost.example.com/orclpdb",
)
embedder = OracleDBEmbedder(
    connection=pool,
    model="DOC_MODEL",
    embedding_dimension=768,
)
embedder.embed(["hello world"])

当连接的方案具有对另一个方案拥有的模型的权限时，可以使用符合方案的模型名称：

shared_embedder = OracleDBEmbedder(
    connection=pool,
    model="MY_OTHER_SCHEMA.MY_ONNX_MODEL",
    embedding_dimension=768,
)
shared_embedder.embed(["hello world"])

以下示例说明如何使用 OpenAI、vLLM、Cohere 和其他提供商配置 Oracle AI Database 嵌入：

OpenAI 示例：

openai_embedder = OracleDBEmbedder(
    connection=pool,
    provider="openai",
    model="text-embedding-3-small",
    provider_options={
        "credential_name": "OPENAI_CRED",
        "url": "https://api.openai.example.com/embeddings",
    },
)
openai_embedder.embed(["hello world"])

Cohere 示例：

cohere_embedder = OracleDBEmbedder(
    connection=pool,
    provider="cohere",
    model="embed-english-v3.0",
    provider_options={
        "credential_name": "COHERE_CRED",
        "url": "https://api.cohere.example.com/embed",
        "input_type": "search_document",
    },
)
cohere_embedder.embed(["hello world"])

与 OpenAI 兼容的服务（如 vLLM）也使用 "openai" 提供程序。当端点不需要 Oracle AI Database 身份证明时，将 host 设置为 "local"：

vllm_embedder = OracleDBEmbedder(
    connection=pool,
    provider="openai",
    model="BAAI/bge-small-en-v1.5",
    provider_options={
        "url": "http://localhost:8080/v1/embeddings",
        "host": "local",
    },
)
vllm_embedder.embed(["hello world"])

双子座示例：

gemini_embedder = OracleDBEmbedder(
    connection=pool,
    provider="googleai",
    model="gemini-embedding-001",
    provider_options={
        "credential_name": "GOOGLEAI_CRED",
        "url": "https://googleapis.example.com/models/",
    },
)
gemini_embedder.embed(["hello world"])

拥抱面示例：

huggingface_embedder = OracleDBEmbedder(
    connection=pool,
    provider="huggingface",
    model=(
        "sentence-transformers/all-MiniLM-L6-v2"
    ),
    provider_options={
        "credential_name": "HF_CRED",
        "url": "https://router.huggingface.example.com/",
    },
)
huggingface_embedder.embed(["hello world"])

可以在不更改存储 API 的情况下配置特定于查询的前缀：

embedder = OracleDBEmbedder(
    connection=pool,
    model="DOC_MODEL",
    query_prefix="search_document: ",
)
embedder.embed(["pizza"], is_query=True)

method `embed`

通过在 Oracle AI Database 中执行 SQL 嵌入一批文本。

参数：
- texts list[str]- 要嵌入的一批原始文本字符串。
- is_query bool- 文本是否为查询。当配置了查询文本时，查询文本将收到 query_prefix。
返回：二维 float32 矩阵，每个输入文本对应一行。
返回类型： numpy.ndarray

示例

embedder = OracleDBEmbedder(
    connection=pool,
    model="DOC_MODEL",
)
matrix = embedder.embed(["alpha", "beta"])
matrix.shape[0]
2

method `embed_async`（异步）

使用 Oracle AI Database SQL 异步嵌入一批文本。

参数：
- texts list[str]- 要嵌入的一批原始文本字符串。
- is_query bool- 文本是否为查询。当配置了查询文本时，查询文本将收到 query_prefix。
返回：二维 float32 矩阵，每个输入文本对应一行。
返回类型： numpy.ndarray

示例

embedder = OracleDBEmbedder(
    connection=pool,
    model="DOC_MODEL",
)
matrix = await embedder.embed_async(["hello"])
matrix.shape
(1, 384)

property（属性）`embedding_dimension`

返回类型： int
说明：返回已配置或推断的嵌入维。
返回值：每个嵌入向量中维数的正数。
返回类型： int

注释

在不与数据库模型联系的情况下，将返回构造器提供的值。否则，属性将探测一次并缓存结果以供将来访问。

示例

embedder = OracleDBEmbedder(
    connection=pool,
    model="DOC_MODEL",
    embedding_dimension=768,
)
embedder.embedding_dimension
768

method `get_vectorizer_config_json`

返回此数据库模型的 Oracle 向量器首选项 JSON。

直接嵌入和管理的混合索引使用相同的模型配置。直接嵌入使用它来决定 VECTOR_EMBEDDING 是否可以表示配置的数据库模型，或者提供程序 JSON 是否需要 DBMS_VECTOR_CHAIN.UTL_TO_EMBEDDING。混合索引将其传递到 DBMS_VECTOR_CHAIN.CREATE_PREFERENCE，然后 Oracle 向量器管道拥有该索引的嵌入工作。

返回：适用于 DBMS_VECTOR_CHAIN.CREATE_PREFERENCE 和 DBMS_VECTOR_CHAIN.VECTORIZER 的紧凑型 JSON 有效负载。
返回类型： str

示例

embedder = OracleDBEmbedder(
    connection=pool,
    model="DOC_MODEL",
    embedding_dimension=768,
)
embedder.get_vectorizer_config_json()
'{"model":"DOC_MODEL"}'
custom_embedder = OracleDBEmbedder(
    connection=pool,
    model="DOC_MODEL",
    input_name="TEXT",
    embedding_dimension=768,
)
custom_embedder.get_vectorizer_config_json()
'{"model":"DOC_MODEL","input_name":"TEXT"}'
shared_embedder = OracleDBEmbedder(
    connection=pool,
    model="MY_OTHER_SCHEMA.MY_ONNX_MODEL",
    embedding_dimension=768,
)
shared_embedder.get_vectorizer_config_json()
'{"model":"MY_OTHER_SCHEMA.MY_ONNX_MODEL"}'
remote_embedder = OracleDBEmbedder(
    connection=pool,
    provider="openai",
    model="text-embedding-3-small",
    provider_options={"host": "local", "url": "http://localhost:8080/v1/embeddings"},
)
remote_embedder.get_vectorizer_config_json()
'{"embedder_spec":{"host":"local","url":"http://localhost:8080/v1/embeddings","provider":"openai","model":"text-embedding-3-small"}}'

property（属性）`max_input_tokens`

返回类型： int
说明：返回用于分块的已配置或推断输入令牌预算。
返回值：一个文本有效负载的实际最大输入标记计数。
返回类型： int

注释

在不与数据库模型联系的情况下，将返回构造器提供的值。否则，该属性将验证大小为估计 512 输入令牌的数据库模型探测器，并将 512 高速缓存为保守回退。它不会在本地运行模型标记器，因此当精度很重要时，请从模型的已记录输入预算中手动设置 max_input_tokens。

示例

embedder = OracleDBEmbedder(
    connection=pool,
    model="DOC_MODEL",
    max_input_tokens=2048,
)
embedder.max_input_tokens
2048

LLM、嵌入器和重新排序器

LLM 接口

class oracleagentmemory.apis.llms.ILlm

method generate（抽象）

method generate_async（抽象、异步）

LLM 响应

class oracleagentmemory.apis.llms.LlmResponse

文本

嵌入器界面

class oracleagentmemory.apis.IEmbedder

method embed（抽象）

method embed_async（抽象、异步）

property（属性）embedding_dimension

property（属性）max_input_tokens

重新分级界面

class oracleagentmemory.apis.IReranker

method rerank

method rerank_async（抽象、异步）

class oracleagentmemory.apis.RerankResponse

class oracleagentmemory.apis.RerankResponseResult

LiteLLM 适配器

class oracleagentmemory.core.llms.LlmApiType

CHAT_COMPLETIONS = ‘ CHAT_COMPLETIONS ’

响应 = 'RESPONSES'

class oracleagentmemory.core.llms.Llm

method generate

method generate_async（异步）

property（属性）supports_vision

class oracleagentmemory.core.embedders.Embedder

method embed

method embed_async（异步）

property（属性）embedding_dimension

property（属性）max_input_tokens

class oracleagentmemory.core.Reranker

method rerank_async（异步）

Oracle DB 嵌入程序

class oracleagentmemory.core.embedders.OracleDBEmbedder

method embed

method embed_async（异步）

property（属性）embedding_dimension

method get_vectorizer_config_json

property（属性）max_input_tokens

class `oracleagentmemory.apis.llms.ILlm`

method `generate`（抽象）

method `generate_async`（抽象、异步）

class `oracleagentmemory.apis.llms.LlmResponse`

class `oracleagentmemory.apis.IEmbedder`

method `embed`（抽象）

method `embed_async`（抽象、异步）

property（属性）`embedding_dimension`

property（属性）`max_input_tokens`

class `oracleagentmemory.apis.IReranker`

method `rerank`

method `rerank_async`（抽象、异步）

class `oracleagentmemory.apis.RerankResponse`

class `oracleagentmemory.apis.RerankResponseResult`

class `oracleagentmemory.core.llms.LlmApiType`

class `oracleagentmemory.core.llms.Llm`

method `generate`

method `generate_async`（异步）

property（属性）`supports_vision`

class `oracleagentmemory.core.embedders.Embedder`

method `embed`

method `embed_async`（异步）

property（属性）`embedding_dimension`

property（属性）`max_input_tokens`

class `oracleagentmemory.core.Reranker`

method `rerank_async`（异步）

class `oracleagentmemory.core.embedders.OracleDBEmbedder`

method `embed`

method `embed_async`（异步）

property（属性）`embedding_dimension`

method `get_vectorizer_config_json`

property（属性）`max_input_tokens`