LLMと埋込み

このページでは、LLMおよび埋込みをOracle Agent Memoryに接続するために使用する抽象インタフェースを示します。

LLMインタフェース

クラス oracleagentmemory.apis.llms.ILlm

ベース: ABC

LLM呼出しの抽象インタフェース。

method generate (抽象)

LLMからのレスポンスを同期的に生成します。

method generate_async (抽象、非同期)

LLMからのレスポンスを非同期で生成します。

LLMレスポンス

クラス oracleagentmemory.apis.llms.LlmResponse

ベース: object

ILlmによって返される小さい正規化されたレスポンス。

テキスト

プライマリ生成テキスト・コンテンツ。

Embedderインタフェース

クラス oracleagentmemory.apis.IEmbedder

ベース: ABC

テキスト・埋込み用の抽象インタフェース。

method embed (抽象)

テキストのバッチを2D float32 NumPy配列に埋め込みます。

method embed_async (抽象、非同期)

テキストのバッチを2D float32 NumPy配列に埋め込みます。

property embedding_dimension

構成メタデータまたはプロバイダ・メタデータから埋込み幅がわかっている場合、サブクラスはこのプロパティをオーバーライドできます。デフォルトの実装では、embed()を1回プローブし、結果サイズをキャッシュします。

property max_input_tokens

モデルの入力予算が構成またはプロバイダ・メタデータからわかっている場合、サブクラスはこのプロパティをオーバーライドできます。デフォルトの実装では、推定512入力トークンにサイズ設定されたプローブが1回検証され、512が保守的なフォールバックとしてキャッシュされます。モデル・トークナイザはローカルで実行されないため、コール元は、モデルの実際の入力予算がわかっているときにmax_input_tokensを手動で設定する必要があります。

LiteLLMアダプタ

クラス oracleagentmemory.core.llms.LlmApiType

ベース: str、Enum

LlmでサポートされているOpenAI互換APIファミリ。

CHAT_COMPLETIONS = 'CHAT_COMPLETIONS'

応答 = 'RESPONSES'

クラス oracleagentmemory.core.llms.Llm

ベース: ILlm

モデル応答を生成するためのアダプタです。

LLMアダプタを作成します。

例

OCI生成AIモデルは、LiteLLMの"oci/..."モデル識別子を使用します。一般的な設定は、LiteLLM固有のキーワード引数を介してOCI APIキー認証の詳細を標準OCI構成ファイルから渡すことです。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ホスト・モデルでは、"openai/gpt-5.1"やOpenAI APIキーなどのLiteLLMモデル識別子が使用されます。チャット完了はデフォルトの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'

vLLMを含む自己ホストOpenAI互換サーバーは、"openai/..."モデル識別子とサーバーの/v1ベースURLを使用してコールされます。エンドポイントで認証が強制されない場合は、"none"などの名目api_keyを渡します。

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

応答を生成します。

method generate_async (非同期)

非同期でレスポンスを生成します。

クラス oracleagentmemory.core.embedders.Embedder

ベース: IEmbedder

プロバイダに支えられた埋込み。

プロバイダに支えられた埋込みを作成します。

例

OCI生成AI埋込みモデルでは、"oci/..."モデル識別子を使用します。一般的な設定は、LiteLLM固有のキーワード引数を介してOCI APIキー認証の詳細を標準OCI構成ファイルから渡すことです。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"])

vLLMを含む自己ホストOpenAI互換の埋込みサーバーでは、サーバーの/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"])

メソッド embed

構成済プロバイダを使用してテキストのバッチを埋め込みます。

method embed_async (非同期)

構成されたプロバイダを使用して、テキストのバッチを非同期に埋め込みます。

property embedding_dimension

ノート:

コンストラクタ提供の値は、プロバイダに連絡せずに返されます。それ以外の場合、プロパティは1回プローブし、結果をキャッシュします。

property max_input_tokens

ノート:

コンストラクタ提供の値は、プロバイダに連絡せずに返されます。それ以外の場合、このプロパティは、推定512入力トークンにサイズ設定されたプロバイダ・プローブを検証し、512を保守的なフォールバックとしてキャッシュします。モデル・トークナイザはローカルで実行されないため、精度が重要な場合は、モデルの文書化された入力予算からmax_input_tokensを手動で設定します。

Oracle DB埋込み

クラス oracleagentmemory.core.embedders.OracleDBEmbedder

ベース: IEmbedder

Oracle Database埋込みSQLを呼び出してテキストを埋め込みます。

この埋込みにより、パッケージの既存の埋込み契約はそのまま保持され、埋込み生成はSQLを介してデータベースに委任されます。直接埋込みは、データベース常駐のモデル構成にVECTOR_EMBEDDINGを優先し、ベクトル化の構成にJSONプロバイダ・パラメータ・サーフェスが必要な場合にDBMS_VECTOR_CHAIN.UTL_TO_EMBEDDINGにフォールバックします。

Oracle Database SQLの実行に裏付けられた埋込みを作成します。

例

Oracle接続プールとDB常駐の埋込みモデルを使用します。

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を実行して、テキストのバッチを埋め込みます。

例

embedder = OracleDBEmbedder(
    connection=pool,
    model="DOC_MODEL",
)
matrix = embedder.embed(["alpha", "beta"])
matrix.shape[0]
2

method embed_async (非同期)

Oracle Database SQLを使用して、テキストのバッチを非同期に埋め込みます。

例

embedder = OracleDBEmbedder(
    connection=pool,
    model="DOC_MODEL",
)
matrix = await embedder.embed_async(["hello"])
matrix.shape
(1, 384)

property embedding_dimension

ノート:

コンストラクタ提供の値は、データベース・モデルに接続せずに返されます。それ以外の場合、プロパティーは1回プローブし、将来のアクセスのために結果をキャッシュします。

例

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

メソッド get_vectorizer_config_json

このDBモデルのOracleベクトル化プリファレンスJSONを返します。

同じモデル構成が、直接埋込みと管理対象ハイブリッド索引によって使用されます。直接埋込みでは、これを使用して、VECTOR_EMBEDDINGが構成済データベース・モデルを表すことができるかどうか、またはプロバイダJSONにDBMS_VECTOR_CHAIN.UTL_TO_EMBEDDINGが必要かどうかを判断します。ハイブリッド索引付けはこれをDBMS_VECTOR_CHAIN.CREATE_PREFERENCEに渡し、Oracleのベクトル化パイプラインがその索引の埋込み作業を所有します。

例

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

ノート:

コンストラクタ提供の値は、データベース・モデルに接続せずに返されます。それ以外の場合、このプロパティは、推定512入力トークンにサイズ設定されたデータベース・モデル・プローブを検証し、512を保守的なフォールバックとしてキャッシュします。モデル・トークナイザはローカルで実行されないため、精度が重要な場合は、モデルの文書化された入力予算からmax_input_tokensを手動で設定します。

例

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