LLMs und Einbettungen

Auf dieser Seite werden die abstrakten Schnittstellen vorgestellt, mit denen LLMs und Einbettungen in den Oracle Agent-Speicher integriert werden.

LLM-Schnittstelle

Klasse oracleagentmemory.apis.llms.ILlm

Basen: ABC

Abstrakte Schnittstelle für LLM-Aufruf.

Methode generate (Übung)

Generieren Sie eine Antwort von einem LLM synchron.

• Parameter:
  • prompt str | Sequence[dict[str, str]]: Entweder eine Nur-Text-Eingabeaufforderung (als einzelne Benutzernachricht behandelt) oder eine Chat-Liste mit Nachrichten, bei der jede Nachricht eine Zuordnung mit mindestens einem "content"-Schlüssel und optional einem "role"-Schlüssel ist.
  • response_json_schema dict[str, Any] | None: Optionales JSON-Schema, das das erwartete Antwortformat beschreibt.
  • **kwargs (Beliebig) – Anbieterspezifische Schlüsselwortargumente, die an das zugrunde liegende Backend weitergeleitet werden.
• Rücksendungen: Normalisierte LLM-Ausgabe.
• Rückgabetyp: LlmResponse

Methode generate_async (abstrakt, asynchron)

Generieren Sie asynchron eine Antwort aus einem LLM.

• Parameter:
  • prompt str | Sequence[dict[str, str]]: Entweder eine Nur-Text-Eingabeaufforderung (als einzelne Benutzernachricht behandelt) oder eine Chat-Liste mit Nachrichten, bei der jede Nachricht eine Zuordnung mit mindestens einem "content"-Schlüssel und optional einem "role"-Schlüssel ist.
  • response_json_schema dict[str, Any] | None: Optionales JSON-Schema, das das erwartete Antwortformat beschreibt.
  • **kwargs (Beliebig) – Anbieterspezifische Schlüsselwortargumente, die an das zugrunde liegende Backend weitergeleitet werden.
• Rückgaben: Normalisierte LLM-Ausgabe.
• Rückgabetyp: LlmResponse

LLM-Antworten

Klasse oracleagentmemory.apis.llms.LlmResponse

Basis: object

Eine kleine normalisierte Antwort, die von ILlm zurückgegeben wird.

• Parameter: Text str

Text

Der primäre generierte Textinhalt.

• Typ: str

Einbettungsschnittstelle

Klasse oracleagentmemory.apis.IEmbedder

Basen: ABC

Abstrakte Schnittstelle für Texteinbettungen.

Methode embed (Übung)

Integrieren Sie eine Reihe von Texten in ein 2D float32 NumPy Array.

• Parameter:
  • Texte list[str]: Einzubettender Textbatch.
  • is_query bool: Gibt an, ob der Batch für den Abfragezeitabruf eingebettet wird.
• Rückgaben: Ein 2D-Array in Form von (len(texts), dim) mit dtype=float32.
• Rückgabetyp: numpy.ndarray

Methode embed_async (abstrakt, asynchron)

Integrieren Sie eine Reihe von Texten in ein 2D float32 NumPy Array.

• Parameter:
  • Texte list[str]: Einzubettender Textbatch.
  • is_query bool: Gibt an, ob der Batch für den Abfragezeitabruf eingebettet wird.
• Rückgaben: Ein 2D-Array in Form von (len(texts), dim) mit dtype=float32.
• Rückgabetyp: numpy.ndarray

LiteLLM-Adapter

Klasse oracleagentmemory.core.llms.LlmApiType

Basis: str, Enum

Unterstützte OpenAI-kompatible API-Familien für Llm.

CHAT_COMPLETIONS *= 'CHAT_COMPLETIONS'*

RESPONSES *= 'Antworten'*

Klasse oracleagentmemory.core.llms.Llm

Basis: ILlm

Adapter zum Generieren von Modellantworten.

LLM-Adapter erstellen

• Parameter:
  • model str: Modell-ID, die an den zugrunde liegenden Modellprovider gesendet wird.
  • api_base str | None – Optionale Basis-URL für einen OpenAI-kompatiblen Endpunkt.
  • api_key str | None: Optionaler API-Schlüssel, der beim Kontaktieren des Providers verwendet wird.
  • api_type LlmApiType: Aufzurufende API-Familie. Verwenden Sie LlmApiType.CHAT_COMPLETIONS für Chatabschlüsse oder LlmApiType.RESPONSES für die Antwort-API. Standard ist LlmApiType.CHAT_COMPLETIONS.
  • stream bool: Gibt an, ob eine Streamingausgabe angefordert werden soll. Der Stream wird intern verbraucht und als einzelne LlmResponse zurückgegeben.
  • Temperatur float | None – Optionale Abtasttemperatur.
  • max_tokens int | None – Optionaler Ausgabetokengrenzwert. Mit api_type=LlmApiType.CHAT_COMPLETIONS wird dies als max_tokens gesendet. Mit api_type=LlmApiType.RESPONSES wird dies als max_output_tokens gesendet.
  • reasoning_effort str | None – Optionaler Begründungsaufwand. Mit api_type=LlmApiType.CHAT_COMPLETIONS wird dies als reasoning_effort gesendet. Mit api_type=LlmApiType.RESPONSES wird dieser in reasoning={"effort": ...} konvertiert.
  • **default_kwargs (Any) – Erweiterte Standard-Schlüsselwortargumente, die für jeden Aufruf angewendet werden. Bevorzugt die oben angegebenen expliziten Parameter für allgemeine Verbindungs- und Generierungseinstellungen. Wenn dieselbe Einstellung sowohl explizit als auch in default_kwargs angegeben wird, hat der explizite Parameter Vorrang.

Beispiele

OCI Generative AI-Modelle verwenden die "oci/..."-Modell-IDs von LiteLLM. Ein gängiges Setup besteht darin, OCI-API-Schlüsselauthentifizierungsdetails aus der OCI-Standardkonfigurationsdatei über LiteLLM-spezifische Schlüsselwortargumente zu übergeben. Das OCI-Python-SDK wird von diesem Package nicht installiert. Anwendungen, die bereits davon abhängig sind, können alternativ ein oci_signer-Objekt übergeben.

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-gehostete Modelle verwenden LiteLLM-Modell-IDs wie "openai/gpt-5.1" und einen OpenAI-API-Schlüssel. Chat-Abschlüsse sind die Standard-API-Familie.

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

Verwenden Sie api_type=LlmApiType.RESPONSES, wenn das Zielmodell über die OpenAI-Antworten-API anstelle von Chatabschlüssen aufgerufen werden soll.

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'

Selbst gehostete OpenAI-kompatible Server, einschließlich vLLM, werden mit einer Modell-ID "openai/..." plus der Basis-URL /v1 des Servers aufgerufen. Übergeben Sie eine nominale api_key, wie "none", wenn der Endpunkt die Authentifizierung nicht erzwingt.

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

Methode generate

Generieren Sie eine Antwort.

• Parameter:
  • prompt str | Sequence[dict[str, str]]: Prompt-Zeichenfolge oder Chatnachrichten. Eine Zeichenfolge wird als eine einzelne Benutzernachricht behandelt.
  • response_json_schema dict[str, Any] | None: Optionales JSON-Schema, das das erwartete Antwortformat beschreibt. Bei dieser Methode wird der provider-native strukturierte Ausgabemechanismus über OpenAI-kompatible response_format verwendet.
  • **kwargs (Beliebig) – Zusätzliche Aufrufparameter, die mit dieser Anforderung gesendet werden. Übergeben Sie api_type=LlmApiType.RESPONSES, um diesen Aufruf über die Responses-API weiterzuleiten.
• Rücksendungen: Normalisierte LLM-Ausgabe.
• Rückgabetyp: LlmResponse

Methode generate_async (asynchron)

Antwort asynchron generieren.

• Parameter:
  • prompt str | Sequence[dict[str, str]]: Prompt-Zeichenfolge oder Chatnachrichten. Eine Zeichenfolge wird als eine einzelne Benutzernachricht behandelt.
  • response_json_schema dict[str, Any] | None: Optionales JSON-Schema, das das erwartete Antwortformat beschreibt. Bei dieser Methode wird der provider-native strukturierte Ausgabemechanismus über OpenAI-kompatible response_format verwendet.
  • **kwargs (Beliebig) – Zusätzliche Aufrufparameter, die mit dieser Anforderung gesendet werden. Übergeben Sie api_type=LlmApiType.RESPONSES, um diesen Aufruf über die Responses-API weiterzuleiten.
• Rücksendungen: Normalisierte LLM-Ausgabe.
• Rückgabetyp: LlmResponse

Klasse oracleagentmemory.core.embedders.Embedder

Basis: IEmbedder

Provider-backed-Einbettung.

Providerbacked Embedder erstellen

• Parameter:
  • model str: Modell-ID, die an den zugrunde liegenden Einbettungsprovider gesendet wird.
  • api_base str | None – Optionale Basis-URL für einen OpenAI-kompatiblen Endpunkt.
  • api_key str | None: Optionaler API-Schlüssel, der beim Kontaktieren des Providers verwendet wird.
  • normalisieren bool – Gibt an, ob Einbettungen, die vom Provider zurückgegeben werden, mit L2 normalisiert werden sollen.
  • query_prefix str | None – Optionales Präfix, das nur beim Einbetten von Abfragetexten hinzugefügt wird.
  • truncate_prompt_tokens int | None – Optionales Eingabetokenlimit, das an Provider weitergeleitet wird, die das Abschneiden von Eingabeaufforderungen mit langer Einbettung unterstützen.
  • **default_kwargs (Beliebige) – Erweiterte Standard-Schlüsselwortargumente, die für jeden Einbettungsaufruf angewendet werden. Bevorzugt die oben angegebenen expliziten Parameter für allgemeine Einstellungen.

Beispiele

OCI Generative AI-Einbettungsmodelle verwenden "oci/..."-Modell-IDs. Ein gängiges Setup besteht darin, OCI-API-Schlüsselauthentifizierungsdetails aus der OCI-Standardkonfigurationsdatei über LiteLLM-spezifische Schlüsselwortargumente zu übergeben. Das OCI-Python-SDK wird von diesem Package nicht installiert. Anwendungen, die bereits davon abhängig sind, können alternativ ein oci_signer-Objekt übergeben.

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-gehostete Einbettungsmodelle verwenden IDs wie "openai/text-embedding-3-small" mit einem OpenAI-API-Schlüssel.

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

Selbst gehostete OpenAI-kompatible Einbettungsserver, einschließlich vLLM, verwenden das Providerpräfix "hosted_vllm/..." mit der Basis-URL /v1 des Servers.

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

Methode embed

Einbetten eines Textbatches mit dem konfigurierten Provider.

• Parameter:
  • texts list[str]: Batch mit einzubettenden Raw-Textzeichenfolgen.
  • is_query bool – Gibt an, ob der Text eine Abfrage ist. Abfragetexte erhalten query_prefix, wenn eine konfiguriert wurde.
• Rückgaben: Eine zweidimensionale float32-Matrix mit den Einbettungsvektoren, die vom Provider zurückgegeben werden.
• Rückgabetyp: numpy.ndarray
• Gelöst: RuntimeError – Wenn die Providerantwort-Payload keine Einbettungsdaten enthält.

Methode embed_async (asynchron)

Einbetten eines Textbatches mit dem konfigurierten Provider asynchron.

• Parameter:
  • texts list[str]: Batch mit einzubettenden Raw-Textzeichenfolgen.
  • is_query bool – Gibt an, ob der Text eine Abfrage ist. Abfragetexte erhalten query_prefix, wenn eine konfiguriert wurde.
• Rückgaben: Eine zweidimensionale float32-Matrix mit den Einbettungsvektoren, die vom Provider zurückgegeben werden.
• Rückgabetyp: numpy.ndarray
• Gelöst: RuntimeError – Wenn die Providerantwort-Payload keine Einbettungsdaten enthält.