LLM、嵌入器及排名器

此頁面顯示用於將 LLM、內嵌及重新排名插入「Oracle 代理程式記憶體」的抽象介面。

LLM 介面

類別 `oracleagentmemory.apis.llms.ILlm`

基本：ABC

LLM 呼叫的抽象介面。

方法 `generate` (摘要)

同步從 LLM 產生回應。

參數：
- 提示 str | Sequence[Message | Mapping[str, str | Sequence[Mapping[str, Any]]]] | ChatMessageTypedDictT – 字串、交談式字典順序或 Message 物件的順序。字串會成為使用者訊息；訊息內容可能包含文字與影像部分。映像檔部分會先經過驗證，然後再傳送給提供者。
- response_json_schema dict[str, Any] | None – 描述預期回應格式的選擇性 JSON 綱要。
- **kwargs ( 任一 ) – 其他呼叫選項。內建的 Llm 接受 api_type=LlmApiType.RESPONSES 來選取「回應 API」與 image_input_limit_config=ImageInputLimitConfig(...)，以覆寫該要求的影像限制。其他關鍵字引數則轉送至底層的後端。
傳回：標準化 LLM 輸出。
傳回類型：LlmResponse

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

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

參數：
- 提示 str | Sequence[Message | Mapping[str, str | Sequence[Mapping[str, Any]]]] | ChatMessageTypedDictT – 字串、交談式字典順序或 Message 物件的順序。字串會成為使用者訊息；訊息內容可能包含文字與影像部分。映像檔部分會先經過驗證，然後再傳送給提供者。
- response_json_schema dict[str, Any] | None – 描述預期回應格式的選擇性 JSON 綱要。
- **kwargs ( 任一 ) – 其他呼叫選項。內建的 Llm 接受 api_type=LlmApiType.RESPONSES 來選取「回應 API」與 image_input_limit_config=ImageInputLimitConfig(...)，以覆寫該要求的影像限制。其他關鍵字引數則轉送至底層的後端。
傳回：標準化 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。

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

重新排名器介面

類別 `oracleagentmemory.apis.IReranker`

基本：ABC

同步與非同步文件重新排名的摘要介面。

實作必須為每個輸入文件傳回一個結果。每個零基輸入索引必須完全出現一次。relevance_score 必須是有限的，而較高的分數必須表示較大的相關性。結果必須從最高分數排序到最低分數。

方法 `rerank`

透過委派至 rerank_async 來同步排列文件的等級。

參數：
- 查詢 str – 用來比較文件的搜尋查詢。
- 文件 list[str] – 穩定輸入順序的候選文件文字。結果索引指的是此清單中的位置。
- **kwargs ( 任一 ) – 提供者特定選項。
傳回：完全符合 len(documents) 結果的排名。每個輸入索引都會出現一次，從最相關到最不相關的順序排序。
傳回類型：RerankResponse

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

以非同步方式依與查詢的關聯來排列文件的等級。

參數：
- 查詢 str – 用來比較文件的搜尋查詢。
- 文件 list[str] – 穩定輸入順序的候選文件文字。結果索引指的是此清單中的位置。
- **kwargs ( 任一 ) – 提供者特定選項。
傳回：完全符合 len(documents) 結果的排名。每個輸入索引都會出現一次，從最相關到最不相關的順序排序。
傳回類型：RerankResponse

類別 `oracleagentmemory.apis.RerankResponse`

基礎：object

完成依相關性分數遞減排序的文件排名。

參數： results list[RerankResponseResult]

類別 `oracleagentmemory.apis.RerankResponseResult`

基礎：object

一個文件的重新排名結果。

參數：
- index int – 輸入清單中文件的零位置。
- relevance_score float – 查詢文件組的相關性分數。較高的值表示較大的相關性。
- document str | None – 提供者傳回文件文字，否則為 None。

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 傳送。
- 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 ( 任一 ) – 會將進階預設關鍵字引數套用至每個呼叫。針對一般連線和產生設定值，偏好上方的明確參數。同時在 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[Message | Mapping[str, str | Sequence[Mapping[str, Any]]]] | ChatMessageTypedDictT – 字串、交談式字典順序或「訊息」物件序列。字串會成為使用者訊息；內容可能包含文字與影像部分。映像檔部分會先經過驗證，然後再傳送給提供者。
- response_json_schema dict[str, Any] | None – 描述預期回應格式的選擇性 JSON 綱要。提供時，此方法會透過 OpenAI 相容的 response_format 使用提供者原生結構化輸出機制。
- **kwargs ( 任一 ) – 其他呼叫參數。傳送 api_type=LlmApiType.RESPONSES 以透過「回應 API」遞送此呼叫。若為影像提示，請傳送 image_input_limit_config=ImageInputLimitConfig(...) 以覆寫此 Llm 執行處理的影像限制；省略的欄位會繼承執行處理組態。其他關鍵字引數會與提供者要求一起傳送。
傳回：標準化 LLM 輸出。
傳回類型：LlmResponse

方法 `generate_async` (非同步)

非同步產生回應。

參數：
- 提示 str | Sequence[Message | Mapping[str, str | Sequence[Mapping[str, Any]]]] | ChatMessageTypedDictT – 字串、提示或交談式訊息序列。字串會成為使用者訊息；內容可能包含文字與影像部分。映像檔部分會先經過驗證，然後再傳送給提供者。
- response_json_schema dict[str, Any] | None – 描述預期回應格式的選擇性 JSON 綱要。提供時，此方法會透過 OpenAI 相容的 response_format 使用提供者原生結構化輸出機制。
- **kwargs ( 任一 ) – 其他呼叫參數。傳送 api_type=LlmApiType.RESPONSES 以透過「回應 API」遞送此呼叫。若為影像提示，請傳送 image_input_limit_config=ImageInputLimitConfig(...) 以覆寫此 Llm 執行處理的影像限制；省略的欄位會繼承執行處理組態。其他關鍵字引數會與提供者要求一起傳送。
傳回：標準化 LLM 輸出。
傳回類型：LlmResponse

特性 `supports_vision`

傳回類型：布林值
描述：傳回此 LLM 是否支援影像輸入，並延遲偵測。

類別 `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 – 轉送給支援截斷長內嵌提示之提供者的選擇性輸入記號限制。
- 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 ( 任一 ) – 會將進階預設關鍵字引數套用至每個內嵌呼叫。偏好上方的明確參數以取得一般設定值。

範例

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。

類別 `oracleagentmemory.core.Reranker`

基本：IReranker

Reranker 以供應商中立的排名介面為後盾。

參數：
- 模型 str – Reranker 模型 ID。在 OCI Generative AI 模型前面加上 oci/，例如 oci/cohere.rerank-v4.0-fast。
- api_base str | None – OpenAI 相容重新排名端點的選擇性基礎 URL。
- api_key str | None – 提供者使用的可選 API 金鑰。
- **default_kwargs ( 任一 ) –
  
  套用至每個重新排名要求的提供者特定選項。
  
  注意： 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."])

建立提供者支持的重新排名器。

方法 `rerank_async` (非同步)

以非同步方式依與查詢的關聯來排列文件的等級。

參數：
- 查詢 str – 用來比較文件的搜尋查詢。
- 文件 list[str] – 穩定輸入順序的候選文件文字。
- **kwargs ( 任一 ) – 轉送給重新排名提供者的提供者特定選項。
傳回：完整的提供者排名，從最高相關性分數排序至最低。
傳回類型：RerankResponse

Oracle DB 嵌入器

類別 `oracleagentmemory.core.embedders.OracleDBEmbedder`

基本：IEmbedder

藉由呼叫 Oracle AI Database 內嵌 SQL 來內嵌文字。

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

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

參數：
- connection object – 具有可呼叫 cursor() 或 acquire() 方法的 Oracle DB 連線或類似集區的物件。
- model str – 模型 ID。對於預設的 "database" 提供者，這必須是資料庫內內嵌模型的無引號 Oracle SQL ID 或綱要限定 ID。連線的綱要必須能夠在 SQL 中解析此模型名稱。對於遠端提供者，請使用該服務預期的模型名稱或提供者特定模型 ID。
- 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 內嵌往返的文字數目上限。
- 提供者 str – 在 Oracle AI Database 中設定的內嵌提供者。預設值 "database" 會使用載入 Oracle Database 的內嵌模型 (通常是 ONNX 格式)。遠端提供者包括 Cohere、OpenAI、Google AI 及 Oracle Cloud Infrastructure Generative AI 等服務。OpenAI 相容服務 (例如 vLLM) 會搭配 provider_options 中的服務端點使用 "openai"。如需支援的提供者及其組態，請參閱 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 範例：

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

Hugging Face 範例：

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)

方法 `embed`

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

特性 `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

重新排名器介面

類別 oracleagentmemory.apis.IReranker

方法 rerank

method rerank_async (抽象、非同步)

類別 oracleagentmemory.apis.RerankResponse

類別 oracleagentmemory.apis.RerankResponseResult

LiteLLM 轉接器

類別 oracleagentmemory.core.llms.LlmApiType

CHAT_COMPLETIONS = 'CHAT_COMPLETIONS'

回應 = 'RESPONSES'

類別 oracleagentmemory.core.llms.Llm

方法 generate

方法 generate_async (非同步)

特性 supports_vision

類別 oracleagentmemory.core.embedders.Embedder

方法 embed

方法 embed_async (非同步)

特性 embedding_dimension

特性 max_input_tokens

類別 oracleagentmemory.core.Reranker

方法 rerank_async (非同步)

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.apis.IReranker`

方法 `rerank`

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

類別 `oracleagentmemory.apis.RerankResponse`

類別 `oracleagentmemory.apis.RerankResponseResult`

類別 `oracleagentmemory.core.llms.LlmApiType`

類別 `oracleagentmemory.core.llms.Llm`

方法 `generate`

方法 `generate_async` (非同步)

特性 `supports_vision`

類別 `oracleagentmemory.core.embedders.Embedder`

方法 `embed`

方法 `embed_async` (非同步)

特性 `embedding_dimension`

特性 `max_input_tokens`

類別 `oracleagentmemory.core.Reranker`

方法 `rerank_async` (非同步)

類別 `oracleagentmemory.core.embedders.OracleDBEmbedder`

方法 `embed`

方法 `embed_async` (非同步)

特性 `embedding_dimension`

方法 `get_vectorizer_config_json`

特性 `max_input_tokens`