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を手動で設定する必要があります。

Rerankerインタフェース

クラス oracleagentmemory.apis.IReranker

ベース: ABC

同期および非同期文書再ランク付け用の抽象インタフェースです。

実装は、入力ドキュメントごとに1つの結果を返す必要があります。ゼロベースの各入力索引は、1回のみ出現する必要があります。relevance_scoreは有限である必要があり、スコアが高いほど関連性が高くなる必要があります。結果は、最高スコアから最低スコアの順に並べる必要があります。

メソッド rerank

rerank_asyncに委任して、ドキュメントを同期的にランク付けします。

method rerank_async (抽象、非同期)

クエリーに関連するドキュメントを非同期にランク付けします。

クラス oracleagentmemory.apis.RerankResponse

ベース: object

ドキュメント・ランキングを関連スコアの降順で完了します。

クラス oracleagentmemory.apis.RerankResponseResult

ベース: object

1つの文書の再ランク付けの結果。

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 (非同期)

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

property supports_vision

クラス 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を手動で設定します。

クラス oracleagentmemory.core.Reranker

ベース: IReranker

Rerankerは、プロバイダに依存しないRerankインタフェースによってサポートされます。

例

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

プロバイダにバックアップされた再ランカを作成します。

method rerank_async (非同期)

クエリーに関連するドキュメントを非同期にランク付けします。

Oracle DB埋込み

クラス oracleagentmemory.core.embedders.OracleDBEmbedder

ベース: IEmbedder

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

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

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

次の例は、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"])

vLLMなどのOpenAI互換サービスでは、"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を実行して、テキストのバッチを埋め込みます。

例

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

method embed_async (非同期)

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

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