LLMと埋込み

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

LLMインタフェース

クラス oracleagentmemory.apis.llms.ILlm

ベース: ABC

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

method generate (抽象)

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

• パラメータ:
  • プロンプト str | Sequence[dict[str, str]]– プレーン・テキスト・プロンプト(単一ユーザー・メッセージとして処理)またはチャット形式のメッセージ・リスト(各メッセージは、少なくとも"content"キーおよびオプションで"role"を含むマッピング)のいずれかです。
  • response_json_schema dict[str, Any] | None– 必要なレスポンス形式を記述するオプションのJSONスキーマ。
  • **kwargs (Any)– 基盤となるバックエンドに転送されるプロバイダ固有のキーワード引数。
• 戻り値:正規化されたLLM出力。
• 戻りタイプ: LlmResponse

method generate_async (抽象、非同期)

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

• パラメータ:
  • プロンプト str | Sequence[dict[str, str]]– プレーン・テキスト・プロンプト(単一ユーザー・メッセージとして処理)またはチャット形式のメッセージ・リスト(各メッセージは、少なくとも"content"キーおよびオプションで"role"を含むマッピング)のいずれかです。
  • response_json_schema dict[str, Any] | None– 必要なレスポンス形式を記述するオプションのJSONスキーマ。
  • **kwargs (Any)– 基盤となるバックエンドに転送されるプロバイダ固有のキーワード引数。
• 戻り値:正規化されたLLM出力。
• 戻りタイプ: LlmResponse

LLMレスポンス

クラス oracleagentmemory.apis.llms.LlmResponse

ベース: object

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

• パラメータ: text str

テキスト

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

• タイプ: str

Embedderインタフェース

クラス oracleagentmemory.apis.IEmbedder

ベース: ABC

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

method embed (抽象)

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

• パラメータ:
  • texts list[str]– 埋め込むテキストのバッチ。
  • is_query bool– バッチが問合せ時取得用に埋め込まれているかどうか。
• 戻り値: dtype=float32を持つ2D配列型の(len(texts), dim)。
• 戻り値の型: numpy.ndarray

method embed_async (抽象、非同期)

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

• パラメータ:
  • texts list[str]– 埋め込むテキストのバッチ。
  • is_query bool– バッチが問合せ時取得用に埋め込まれているかどうか。
• 戻り値: dtype=float32を持つ2D配列型の(len(texts), dim)。
• 戻り値の型: numpy.ndarray

LiteLLMアダプタ

クラス oracleagentmemory.core.llms.LlmApiType

ベース: str、Enum

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

CHAT_COMPLETIONS *= 'CHAT_COMPLETIONS'*

RESPONSES *= '応答'*

クラス oracleagentmemory.core.llms.Llm

ベース: ILlm

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

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

• パラメータ:
  • model str– 基礎となるモデル・プロバイダに送信されるモデル識別子。
  • api_base str | None–OpenAI互換エンドポイントのオプションのベースURL。
  • api_key str | None– プロバイダへの接続時に使用されるオプションのAPIキー。
  • api_type LlmApiType– 呼び出すAPIファミリ。チャット完了の場合はLlmApiType.CHAT_COMPLETIONS、レスポンスAPIの場合はLlmApiType.RESPONSESを使用します。デフォルトは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 (Any)– すべての呼び出しに適用される拡張デフォルトキーワード引数。一般的な接続および生成設定については、前述の明示的なパラメータを優先してください。明示的にもdefault_kwargsにも同じ設定が指定されている場合は、明示的なパラメータが優先されます。

例

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

応答を生成します。

• パラメータ:
  • prompt str | Sequence[dict[str, str]]– プロンプト文字列またはチャットメッセージ。文字列は、単一のユーザー・メッセージとして扱われます。
  • response_json_schema dict[str, Any] | None– 必要なレスポンス形式を記述するオプションのJSONスキーマ。指定した場合、このメソッドはOpenAI互換のresponse_formatを介してプロバイダ・ネイティブの構造化出力メカニズムを使用します。
  • **kwargs (Any)– この要求とともに送信される追加のコールパラメータ。レスポンスAPIを介してこのコールをルーティングするには、api_type=LlmApiType.RESPONSESを渡します。
• 戻り値:正規化されたLLM出力。
• 戻りタイプ: LlmResponse

method generate_async (非同期)

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

• パラメータ:
  • prompt str | Sequence[dict[str, str]]– プロンプト文字列またはチャットメッセージ。文字列は、単一のユーザー・メッセージとして扱われます。
  • response_json_schema dict[str, Any] | None– 必要なレスポンス形式を記述するオプションのJSONスキーマ。指定した場合、このメソッドはOpenAI互換のresponse_formatを介してプロバイダ・ネイティブの構造化出力メカニズムを使用します。
  • **kwargs (Any)– この要求とともに送信される追加のコールパラメータ。レスポンスAPIを介してこのコールをルーティングするには、api_type=LlmApiType.RESPONSESを渡します。
• 戻り値:正規化されたLLM出力。
• 戻りタイプ: LlmResponse

クラス oracleagentmemory.core.embedders.Embedder

ベース: IEmbedder

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

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

• パラメータ:
  • model str– 基礎となる埋込みプロバイダに送信されるモデル識別子。
  • 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 (Any)– すべての埋め込み呼び出しに適用される拡張デフォルトキーワード引数。共通設定については、前述の明示的なパラメータを優先してください。

例

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

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

• パラメータ:
  • texts list[str]– 埋め込む生のテキスト文字列のバッチ。
  • is_query bool– テキストがクエリーであるかどうか。問合せテキストは、構成時にquery_prefixを受け取ります。
• 戻り値:プロバイダから返される埋込みベクトルを含む2次元のfloat32マトリックス。
• 戻り値の型: numpy.ndarray
• Raises: RuntimeError– プロバイダ・レスポンス・ペイロードにデータの埋込みが含まれていない場合。

method embed_async (非同期)

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

• パラメータ:
  • texts list[str]– 埋め込む生のテキスト文字列のバッチ。
  • is_query bool– テキストがクエリーであるかどうか。問合せテキストは、構成時にquery_prefixを受け取ります。
• 戻り値:プロバイダから返される埋込みベクトルを含む2次元のfloat32マトリックス。
• 戻り値の型: numpy.ndarray
• Raises: RuntimeError– プロバイダ・レスポンス・ペイロードにデータの埋込みが含まれていない場合。