LLM 和嵌入程序

此页提供了用于将 LLM 和嵌入程序插入到 Oracle 代理内存中的抽象接口。

LLM 接口

class oracleagentmemory.apis.llms.ILlm

基础：ABC

LLM 调用的抽象接口。

method generate（抽象）

同步从 LLM 生成响应。

• 参数：
  • prompt str | Sequence[dict[str, str]]- 纯文本提示（以单个用户消息形式处理）或聊天式消息列表，其中每条消息都是至少包含 "content" 键和可选 "role" 的映射。
  • response_json_schema dict[str, Any] | None- 描述预期响应格式的可选 JSON 方案。
  • **kwargs ( Any )- 转发到底层后端的特定于提供程序的关键字参数。
• 返回值：标准化 LLM 输出。
• 返回类型：LlmResponse

method generate_async（抽象、异步）

从 LLM 异步生成响应。

• 参数：
  • prompt str | Sequence[dict[str, str]]- 纯文本提示（以单个用户消息形式处理）或聊天式消息列表，其中每条消息都是至少包含 "content" 键和可选 "role" 的映射。
  • response_json_schema dict[str, Any] | None- 描述预期响应格式的可选 JSON 方案。
  • **kwargs ( Any )- 转发到底层后端的特定于提供程序的关键字参数。
• 返回值：标准化 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

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 发送。"oci/openai.gpt-5" 模型系列不支持此设置。
  • reasoning_effort str | None- 可选推理工作。使用 api_type=LlmApiType.CHAT_COMPLETIONS 时，此消息将作为 reasoning_effort 发送。使用 api_type=LlmApiType.RESPONSES 时，将转换为 reasoning={"effort": ...}。
  • **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[dict[str, str]]- 提示字符串或聊天消息。字符串被视为单个用户消息。
  • response_json_schema dict[str, Any] | None- 描述预期响应格式的可选 JSON 方案。如果提供，此方法将通过与 OpenAI 兼容的 response_format 使用提供程序本机结构化输出机制。
  • **kwargs ( Any )- 随此请求发送的附加调用参数。通过 api_type=LlmApiType.RESPONSES 通过 Responses API 传送此调用。
• 返回值：标准化 LLM 输出。
• 返回类型：LlmResponse

method generate_async（异步）

异步生成响应。

• 参数：
  • prompt str | Sequence[dict[str, str]]- 提示字符串或聊天消息。字符串被视为单个用户消息。
  • response_json_schema dict[str, Any] | None- 描述预期响应格式的可选 JSON 方案。如果提供，此方法将通过与 OpenAI 兼容的 response_format 使用提供程序本机结构化输出机制。
  • **kwargs ( Any )- 随此请求发送的附加调用参数。通过 api_type=LlmApiType.RESPONSES 通过 Responses API 传送此调用。
• 返回值：标准化 LLM 输出。
• 返回类型：LlmResponse

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- 转发给支持截断长嵌入提示的提供者的可选输入令牌限制。
  • **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。

Oracle DB 嵌入程序

class oracleagentmemory.core.embedders.OracleDBEmbedder

基础：IEmbedder

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

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

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

• 参数：
  • connection object- 具有可调用的 cursor() 或 acquire() 方法的 Oracle DB 连接或类似池的对象。
  • model str- 数据库内嵌入模型的未加引号的 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 嵌入往返中的最大文本数。

示例

使用 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"])

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

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

method embed

通过在 Oracle 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 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"}'

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