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

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 发送。使用 api_type=LlmApiType.RESPONSES 时，此消息将作为 max_output_tokens 发送。
  • 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 密钥。
  • normalize bool- 是否对提供者返回的嵌入进行 L2 规范化。
  • query_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。
• 返回值：提供方返回的嵌入向量的二维 float32 矩阵。
• 返回类型： numpy.ndarray
• 引发：RuntimeError - 如果提供程序响应有效负载不包括嵌入数据。

method embed_async（异步）

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

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