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

特性 `embedding_dimension`

退貨類型：整數
描述：傳回此內嵌程式所產生的內嵌項目大小。

從組態或提供者描述資料知道內嵌寬度時，子類別可以覆寫此特性。預設實作會探測 embed() 一次，並快取結果大小。

傳回：每個內嵌向量中的浮點數值正數。
傳回類型：整數

特性 `max_input_tokens`

退貨類型：整數
描述：傳回支援的輸入記號上限。

當模型的輸入預算來自組態或提供者中繼資料時，子類別可以置換此特性。預設實作會驗證大小為預估 512 輸入記號的探測一次，並將 512 快取為保守的後援。它不會在本機執行模型記號器，因此當已知模型的實際輸入預算時，呼叫者應手動設定 max_input_tokens。

傳回：一個文字有效負載的正數輸入記號計數上限。
傳回類型：整數

LiteLLM 轉接器

類別 `oracleagentmemory.core.llms.LlmApiType`

基礎：str、Enum

支援 OpenAI 相容的 Llm API 系列。

CHAT_COMPLETIONS = 'CHAT_COMPLETIONS'

回應 = 'RESPONSES'

類別 `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 傳送。"oci/openai.gpt-5" 模型系列不支援此功能。
- 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 金鑰。
- 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 ( 任一 ) – 會將進階預設關鍵字引數套用至每個內嵌呼叫。偏好上方的明確參數以取得一般設定值。

範例

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 和非查詢文字 document_prefix。
傳回：包含提供者傳回之內嵌向量的二維 float32 矩陣。
傳回類型： numpy.ndarray
發出：RuntimeError – 如果提供者回應有效負載未包含內嵌資料，

方法 `embed_async` (非同步)

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

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

特性 `embedding_dimension`

退貨類型：整數
描述：傳回已設定或推斷的內嵌維度。
傳回：每個內嵌向量中的正數維度。
傳回類型：整數

注意事項

系統會傳回建構子提供的值，但不會聯絡提供者。否則，該特性會探測一次並快取結果。

特性 `max_input_tokens`

退貨類型：整數
描述：傳回已設定或推斷的內嵌輸入記號限制。
傳回：一個文字有效負載的正數輸入記號計數上限。
傳回類型：整數

注意事項

系統會傳回建構子提供的值，但不會聯絡提供者。否則，該特性會驗證大小為預估 512 輸入記號的提供者探測，並將 512 快取為保守的後援。它不會在本機執行模型記號器，因此在精確度很重要時，從模型記載的輸入預算手動設定 max_input_tokens。

Oracle DB 嵌入器

類別 `oracleagentmemory.core.embedders.OracleDBEmbedder`

基本：IEmbedder

呼叫 Oracle Database 內嵌 SQL 以內嵌文字。

此內嵌程式透過 SQL 將內嵌產生委派至資料庫時，會保持套件的現有內嵌程式合約不變。當向量化程式組態需要 JSON 提供者參數曲面時，直接內嵌會偏好使用 VECTOR_EMBEDDING 作為資料庫常駐模型組態，並落回 DBMS_VECTOR_CHAIN.UTL_TO_EMBEDDING。

建立由 Oracle Database SQL 執行支援的內嵌程式。

參數：
- connection object – 具有可呼叫 cursor() 或 acquire() 方法的 Oracle DB 連線或類似集區的物件。
- model str – 資料庫內內嵌模型的無引號 Oracle SQL ID 或綱要限定 ID。連線的綱要必須能夠在 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 – 是否從資料庫擷取內嵌項目後，將內嵌項目標準化。
- 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)

方法 `embed`

在 Oracle Database 中執行 SQL 來內嵌一批文字。

參數：
- 環境定義 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

方法 `embed_async` (非同步)

使用 Oracle Database SQL 以非同步方式內嵌一批文字。

參數：
- 環境定義 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)

特性 `embedding_dimension`

退貨類型：整數
描述：傳回已設定或推斷的內嵌維度。
傳回：每個內嵌向量中的正數維度。
傳回類型：整數

注意事項

傳回建構子提供的值，但未連線資料庫模型。否則，該屬性會探測一次，並將結果快取以供未來存取。

範例

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

方法 `get_vectorizer_config_json`

傳回此資料庫模型的 Oracle 向量設定程式偏好設定 JSON。

直接內嵌和受管理的混合索引會使用相同的模型組態。直接內嵌使用它來決定 VECTOR_EMBEDDING 是否可以代表設定的資料庫模型，或提供者 JSON 是否需要 DBMS_VECTOR_CHAIN.UTL_TO_EMBEDDING。混合編製索引會將其傳遞至 DBMS_VECTOR_CHAIN.CREATE_PREFERENCE，然後 Oracle 的向量化程式管線擁有該索引的內嵌工作。

傳回：使用 DBMS_VECTOR_CHAIN.VECTORIZER 壓縮適合 DBMS_VECTOR_CHAIN.CREATE_PREFERENCE 的 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"}'

特性 `max_input_tokens`

退貨類型：整數
描述：傳回用於分區的已設定或推斷輸入權杖預算。
傳回：一個文字有效負載的正數輸入記號計數上限。
傳回類型：整數

注意事項

傳回建構子提供的值，但未連線資料庫模型。否則，此特性會驗證大小為預估 512 輸入記號的資料庫模型探測，並將 512 快取為保守的後援。它不會在本機執行模型記號器，因此在精確度很重要時，從模型記載的輸入預算手動設定 max_input_tokens。

範例

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

LLM 和嵌入器

LLM 介面

類別 oracleagentmemory.apis.llms.ILlm

方法 generate (摘要)

method generate_async (抽象、非同步)

LLM 回應

類別 oracleagentmemory.apis.llms.LlmResponse

文字

內嵌介面

類別 oracleagentmemory.apis.IEmbedder

方法 embed (摘要)

method embed_async (抽象、非同步)

特性 embedding_dimension

特性 max_input_tokens

LiteLLM 轉接器

類別 oracleagentmemory.core.llms.LlmApiType

CHAT_COMPLETIONS = 'CHAT_COMPLETIONS'

回應 = 'RESPONSES'

類別 oracleagentmemory.core.llms.Llm

方法 generate

方法 generate_async (非同步)

類別 oracleagentmemory.core.embedders.Embedder

方法 embed

方法 embed_async (非同步)

特性 embedding_dimension

特性 max_input_tokens

Oracle DB 嵌入器

類別 oracleagentmemory.core.embedders.OracleDBEmbedder

方法 embed

方法 embed_async (非同步)

特性 embedding_dimension

方法 get_vectorizer_config_json

特性 max_input_tokens

類別 `oracleagentmemory.apis.llms.ILlm`

方法 `generate` (摘要)

method `generate_async` (抽象、非同步)

類別 `oracleagentmemory.apis.llms.LlmResponse`

類別 `oracleagentmemory.apis.IEmbedder`

方法 `embed` (摘要)

method `embed_async` (抽象、非同步)

特性 `embedding_dimension`

特性 `max_input_tokens`

類別 `oracleagentmemory.core.llms.LlmApiType`

類別 `oracleagentmemory.core.llms.Llm`

方法 `generate`

方法 `generate_async` (非同步)

類別 `oracleagentmemory.core.embedders.Embedder`

方法 `embed`

方法 `embed_async` (非同步)

特性 `embedding_dimension`

特性 `max_input_tokens`

類別 `oracleagentmemory.core.embedders.OracleDBEmbedder`

方法 `embed`

方法 `embed_async` (非同步)

特性 `embedding_dimension`

方法 `get_vectorizer_config_json`

特性 `max_input_tokens`