LLM 和嵌入器

此頁面顯示將 LLM 和內嵌程式插入「Oracle 代理程式記憶體」的抽象介面。

LLM 介面

類別 oracleagentmemory.apis.llms.ILlm

基本：ABC

LLM 呼叫的抽象介面。

方法 generate (摘要)

同步從 LLM 產生回應。

• 參數：
  • 提示 str | Sequence[dict[str, str]] – 純文字提示 (視為單一使用者訊息) 或交談式的訊息清單，其中每個訊息都是至少具有 "content" 索引鍵且選擇性地為 "role" 的對應。
  • response_json_schema dict[str, Any] | None – 描述預期回應格式的選擇性 JSON 綱要。
  • **kwargs ( 任一 ) – 會將提供者特定的關鍵字引數轉送至相關後端。
• 傳回：標準化 LLM 輸出。
• 傳回類型：LlmResponse

method generate_async (抽象、非同步)

以非同步方式從 LLM 產生回應。

• 參數：
  • 提示 str | Sequence[dict[str, str]] – 純文字提示 (視為單一使用者訊息) 或交談式的訊息清單，其中每個訊息都是至少具有 "content" 鍵值且選擇性地為 "role" 的對應。
  • response_json_schema dict[str, Any] | None – 描述預期回應格式的選擇性 JSON 綱要。
  • **kwargs ( 任一 ) – 會將提供者特定的關鍵字引數轉送至相關後端。
• 傳回：標準化 LLM 輸出。
• 傳回類型：LlmResponse

LLM 回應

類別 oracleagentmemory.apis.llms.LlmResponse

基礎：object

ILlm 傳回的小型標準化回應。

• 參數：文字 str

文字

主要產生的文字內容。

• 類型： str

內嵌介面

類別 oracleagentmemory.apis.IEmbedder

基本：ABC

文字內嵌器的抽象介面 。

方法 embed (摘要)

將一批文字嵌入到 2D float32 NumPy 陣列中。

• 參數：
  • 環境定義 list[str] – 要嵌入的文字批次。
  • is_query bool – 是否內嵌批次以進行查詢階段擷取。
• 傳回：使用 dtype=float32 形成 (len(texts), dim) 的 2D 陣列。
• 傳回類型： numpy.ndarray

method embed_async (抽象、非同步)

將一批文字嵌入到 2D float32 NumPy 陣列中。

• 參數：
  • 環境定義 list[str] – 要嵌入的文字批次。
  • is_query bool – 是否內嵌批次以進行查詢階段擷取。
• 傳回：使用 dtype=float32 形成 (len(texts), dim) 的 2D 陣列。
• 傳回類型： numpy.ndarray

LiteLLM 轉接器

類別 oracleagentmemory.core.llms.LlmApiType

基礎：str、Enum

支援適用於 Llm 的 OpenAI 相容 API 系列。

CHAT_COMPLETIONS *= 'CHAT_COMPLETIONS'*

回應 *= 「回應」*

類別 oracleagentmemory.core.llms.Llm

基本：ILlm

用於產生模型回應的轉接器。

建立 LLM 轉接器。

• 參數：
  • 模型 str – 傳送給基礎模型提供者的模型 ID。
  • 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 ( 任一 ) – 會將進階預設關鍵字引數套用至每個呼叫。針對一般連線和產生設定值，偏好上方的明確參數。同時在 default_kwargs 中提供相同的設定時，會優先使用明確的參數。

範例

OCI Generative AI 模型使用 LiteLLM 的 "oci/..." 模型識別碼。一般設定是透過 LiteLLM 特定關鍵字引數，從標準 OCI 組態檔傳送 OCI API 金鑰驗證明細。此套裝程式未安裝 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/..." 模型 ID 加上伺服器的 /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.")

方法 generate

產生回應。

• 參數：
  • 提示 str | Sequence[dict[str, str]] – 提示字串或交談訊息。字串會被視為單一使用者訊息。
  • response_json_schema dict[str, Any] | None – 描述預期回應格式的選擇性 JSON 綱要。如果提供，此方法會透過 OpenAI 相容的 response_format 使用提供者原生結構化輸出機制。
  • **kwargs ( 任一 ) – 使用此要求傳送的其他呼叫參數。傳送 api_type=LlmApiType.RESPONSES 以透過「回應 API」遞送此呼叫。
• 傳回：標準化 LLM 輸出。
• 傳回類型：LlmResponse

方法 generate_async (非同步)

非同步產生回應。

• 參數：
  • 提示 str | Sequence[dict[str, str]] – 提示字串或交談訊息。字串會被視為單一使用者訊息。
  • response_json_schema dict[str, Any] | None – 描述預期回應格式的選擇性 JSON 綱要。如果提供，此方法會透過 OpenAI 相容的 response_format 使用提供者原生結構化輸出機制。
  • **kwargs ( 任一 ) – 使用此要求傳送的其他呼叫參數。傳送 api_type=LlmApiType.RESPONSES 以透過「回應 API」遞送此呼叫。
• 傳回：標準化 LLM 輸出。
• 傳回類型：LlmResponse

類別 oracleagentmemory.core.embedders.Embedder

基本：IEmbedder

提供者支持的嵌入器。

建立提供者支持的嵌入器。

• 參數：
  • 模型 str – 傳送給基礎內嵌提供者的模型 ID。
  • 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 ( 任一 ) – 會將進階預設關鍵字引數套用至每個內嵌呼叫。偏好上方的明確參數以取得一般設定值。

範例

OCI Generative AI 嵌入模型使用 "oci/..." 模型識別碼。一般設定是透過 LiteLLM 特定關鍵字引數，從標準 OCI 組態檔傳送 OCI API 金鑰驗證明細。此套裝程式未安裝 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/text-embedding-3-small" 與 OpenAI API 金鑰。

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)，請使用 "hosted_vllm/..." 提供者前置碼搭配伺服器的 /v1 基本 URL。

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

方法 embed

使用已設定的提供者內嵌一批文字。

• 參數：
  • 環境定義 list[str] – 要嵌入的原始文字字串批次。
  • is_query bool – 文字是否為查詢。設定查詢文字時，會收到 query_prefix。
• 傳回：包含提供者傳回之內嵌向量的二維 float32 矩陣。
• 傳回類型： numpy.ndarray
• 發出：RuntimeError – 如果提供者回應有效負載未包含內嵌資料，

方法 embed_async (非同步)

使用設定的提供者以非同步方式內嵌一批文字。

• 參數：
  • 環境定義 list[str] – 要內嵌的原始文字字串批次。
  • is_query bool – 文字是否為查詢。設定查詢文字時，會收到 query_prefix。
• 傳回：包含提供者傳回之內嵌向量的二維 float32 矩陣。
• 傳回類型： numpy.ndarray
• 發出：RuntimeError – 如果提供者回應有效負載未包含內嵌資料，