LLMs, Einbettungen und Reranker

Auf dieser Seite werden die abstrakten Schnittstellen vorgestellt, mit denen LLMs, Einbettungen und Reranker 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[Message | Mapping[str, str | Sequence[Mapping[str, Any]]]] | ChatMessageTypedDictT: Eine Zeichenfolge, eine Dictionary-Sequenz im Chatstil oder eine Sequenz von Message-Objekten. Zeichenfolgen werden zu Benutzernachrichten; Nachrichteninhalte können Text- und Bildteile enthalten. Bildteile werden validiert, bevor sie an den Provider gesendet werden.
  • response_json_schema dict[str, Any] | None: Optionales JSON-Schema, das das erwartete Antwortformat beschreibt.
  • **kwargs (Beliebig) – Zusätzliche Anrufoptionen. Die integrierte Llm akzeptiert api_type=LlmApiType.RESPONSES, um die Antwort-API auszuwählen, und image_input_limit_config=ImageInputLimitConfig(...), um die Bildlimits für diese Anforderung außer Kraft zu setzen. Andere Schlüsselwortargumente werden an das zugrunde liegende Backend weitergeleitet.
• 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[Message | Mapping[str, str | Sequence[Mapping[str, Any]]]] | ChatMessageTypedDictT: Eine Zeichenfolge, eine Dictionary-Sequenz im Chatstil oder eine Sequenz von Message-Objekten. Zeichenfolgen werden zu Benutzernachrichten; Nachrichteninhalte können Text- und Bildteile enthalten. Bildteile werden validiert, bevor sie an den Provider gesendet werden.
  • response_json_schema dict[str, Any] | None: Optionales JSON-Schema, das das erwartete Antwortformat beschreibt.
  • **kwargs (Beliebig) – Zusätzliche Anrufoptionen. Die integrierte Llm akzeptiert api_type=LlmApiType.RESPONSES, um die Antwort-API auszuwählen, und image_input_limit_config=ImageInputLimitConfig(...), um die Bildlimits für diese Anforderung außer Kraft zu setzen. Andere Schlüsselwortargumente werden an das zugrunde liegende Backend weitergeleitet.
• Rücksendungen: 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

Eigenschaft embedding_dimension

• Rückgabetyp: int
• Beschreibung: Geben Sie die Größe der Einbettungen zurück, die von diesem Einbettungsmodul erzeugt werden.

Unterklassen können diese Eigenschaft außer Kraft setzen, wenn die Einbettungsbreite aus Konfigurations- oder Providermetadaten bekannt ist. Die Standardimplementierung prüft einmal embed() und cacht die Ergebnisgröße.

• Rückgaben: Positive Anzahl Gleitkommawerte in jedem Einbettungsvektor.
• Rückgabetyp: int

Eigenschaft max_input_tokens

• Rückgabetyp: int
• Beschreibung: Gibt die maximal unterstützten Eingabetoken zurück.

Unterklassen können diese Eigenschaft überschreiben, wenn das Eingabebudget des Modells aus Konfigurations- oder Providermetadaten bekannt ist. Die Standardimplementierung validiert eine Stichprobengröße einmal auf geschätzte 512-Eingabetoken und cacht 512 als konservatives Fallback. Ein Modell-Tokenizer wird nicht lokal ausgeführt. Daher sollten Aufrufer max_input_tokens manuell festlegen, wenn das tatsächliche Eingabebudget des Modells bekannt ist.

• Rückgaben: Die maximale Anzahl positiver Eingabe-Token für eine Text-Payload.
• Rückgabetyp: int

Reranker-Schnittstelle

Klasse oracleagentmemory.apis.IReranker

Basen: ABC

Abstrakte Schnittstelle für synchrones und asynchrones Dokumenten-Reranking.

Implementierungen müssen für jedes Eingabedokument ein Ergebnis zurückgeben. Jeder nullbasierte Eingabeindex muss genau einmal angezeigt werden. relevance_score muss endlich sein, und höhere Scores müssen eine größere Relevanz angeben. Die Ergebnisse müssen vom höchsten bis zum niedrigsten Score sortiert werden.

Methode rerank

Ordnen Sie Dokumente synchron an, indem Sie an rerank_async delegieren.

• Parameter:
  • query str – Suchabfrage, mit der die Dokumente verglichen werden.
  • Dokumente list[str]: Text des Kandidatendokuments in stabiler Eingabereihenfolge. Ergebnisindizes beziehen sich auf Stellen in dieser Liste.
  • **kwargs (Beliebig) – Providerspezifische Optionen.
• Rückgaben: Vollständiges Ranking mit genau len(documents)-Ergebnissen. Jeder Input-Index erscheint einmal, geordnet von am relevantesten bis am wenigsten relevant.
• Rückgabetyp: RerankResponse

Methode rerank_async (abstrakt, asynchron)

Ordnen Sie Dokumente asynchron nach Relevanz für eine Abfrage ein.

• Parameter:
  • query str – Suchabfrage, mit der die Dokumente verglichen werden.
  • Dokumente list[str]: Text des Kandidatendokuments in stabiler Eingabereihenfolge. Ergebnisindizes beziehen sich auf Stellen in dieser Liste.
  • **kwargs (Beliebig) – Providerspezifische Optionen.
• Rückgaben: Vollständiges Ranking mit genau len(documents)-Ergebnissen. Jeder Input-Index erscheint einmal, geordnet von am relevantesten bis am wenigsten relevant.
• Rückgabetyp: RerankResponse

Klasse oracleagentmemory.apis.RerankResponse

Basis: object

Schließen Sie die Dokumenteneinstufung nach absteigender Relevanz ab.

• Parameter: Ergebnisse list[RerankResponseResult]

Klasse oracleagentmemory.apis.RerankResponseResult

Basis: object

Ergebnis der erneuten Einstufung eines Dokuments.

• Parameter:
  • Index int – Nullbasierte Position des Dokuments in der Eingabeliste.
  • relevance_score float: Relevanzscore für das Abfrage-Dokument-Paar. Höhere Werte bedeuten höhere Relevanz.
  • Dokument str | None: Der Dokumenttext, als der Provider ihn zurückgegeben hat, andernfalls None.

LiteLLM-Adapter

Klasse oracleagentmemory.core.llms.LlmApiType

Basis: str, Enum

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

CHAT_COMPLETIONS = 'CHAT_COMPLETIONS'

RESPONSES = 'RESPONSES'

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 Responses-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.
  • 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.
  • enable_structured_output_reminder bool: Gibt an, ob ein Schema für die strukturierte Ausgabe an den Prompt angehängt werden soll, wenn eine strukturierte Ausgabe angefordert wird. Wenn diese Option ausgelassen wird, folgt die Standardroute der Modellroute: Sie ist für gehostete vLLM- und nicht geschlossene Modelle auf der expliziten "openai/..."-Route von LiteLLM aktiviert. Legen Sie dies explizit für Bare-Modellnamen oder andere benutzerdefinierte Endpunkte fest.
  • supports_vision bool: Gibt an, ob dieses Modell Bildinhalt in Generierungs-Prompts akzeptiert. Wird er ausgelassen, wird die Unterstützung faul erkannt: Der Adapter prüft zunächst die Modellmetadaten und sendet, wenn Metadaten nicht verfügbar sind, eine feste Red-Image-Sonde. Setzen Sie diesen Wert auf True oder False, um die Erkennung zu überspringen.
  • image_input_limit_config ImageInputLimitConfig – Optionale Grenzwerte für Raw-Images und Images pro Anforderung. Ausgelassene Felder verwenden SDK-Standardwerte. Die Validierung bleibt für jede Bildanforderung aktiviert.
  • max_concurrent_requests int | None – Maximale Anzahl von asynchronen Anforderungen, die über diese LLM-Instanz zulässig sind. Lassen Sie den Wert aus, um 16 zu verwenden. Übergeben Sie None, um die Begrenzung des gleichzeitigen Zugriffs zu deaktivieren. Legen Sie dies explizit fest, wenn der Endpunkt ein anderes Verhalten benötigt.
  • proxy str | None – Optionale Proxy-URL für Provideranforderungen. Wenn angegeben, hat dieser explizite Proxy Vorrang vor Proxyeinstellungen aus der Umgebung. Wenn diese Option ausgelassen wird, werden Umgebungsproxyeinstellungen verwendet, wenn trust_env aktiviert ist.
  • trust_env bool: Gibt an, ob der Provider Proxy- und TLS-Einstellungen aus Umgebungsvariablen liest. Der Standardwert ist True, wenn er ausgelassen wird. Setzen Sie diesen Wert auf False, um diese Umgebungseinstellungen zu ignorieren. Eine explizite proxy wird weiterhin verwendet.
  • key_file str | None – Optionaler Pfad zu der Private-Key-Datei des Clients im PEM-Format. Geben Sie sie zusammen mit cert_file an, wenn der Server gegenseitige TLS erfordert.
  • cert_file str | None – Optionaler Pfad zu der Clientzertifikatskettendatei im PEM-Format. Geben Sie sie zusammen mit key_file an, wenn der Server gegenseitige TLS erfordert.
  • ca_file str | None – Optionaler Pfad zu einem vertrauenswürdigen CA-Zertifikat oder -Bundle im PEM-Format, mit dem das Serverzertifikat überprüft wird. Verwenden Sie diese Option für eine private oder anderweitig nicht systembezogene CA.
  • **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[Message | Mapping[str, str | Sequence[Mapping[str, Any]]]] | ChatMessageTypedDictT: Eine Zeichenfolge, eine Dictionary-Sequenz im Chatstil oder eine Sequenz von Nachrichtenobjekten. Zeichenfolgen werden zu Benutzernachrichten; Inhalte können Text- und Bildteile enthalten. Bildteile werden validiert, bevor sie an den Provider gesendet werden.
  • 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. Übergeben Sie api_type=LlmApiType.RESPONSES, um diesen Aufruf über die Responses-API weiterzuleiten. Bei Image-Prompts übergeben Sie image_input_limit_config=ImageInputLimitConfig(...), um die Imagelimits dieser Llm-Instanz für diese Anforderung außer Kraft zu setzen. Ausgelassene Felder erben die Instanzkonfiguration. Andere Schlüsselwortargumente werden mit der Provideranforderung gesendet.
• Rücksendungen: Normalisierte LLM-Ausgabe.
• Rückgabetyp: LlmResponse

Methode generate_async (asynchron)

Antwort asynchron generieren.

• Parameter:
  • prompt str | Sequence[Message | Mapping[str, str | Sequence[Mapping[str, Any]]]] | ChatMessageTypedDictT: Eine Zeichenfolge, ein Prompt oder eine Nachrichtensequenz im Chatstil. Zeichenfolgen werden zu Benutzernachrichten; Inhalte können Text- und Bildteile enthalten. Bildteile werden validiert, bevor sie an den Provider gesendet werden.
  • 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. Übergeben Sie api_type=LlmApiType.RESPONSES, um diesen Aufruf über die Responses-API weiterzuleiten. Bei Image-Prompts übergeben Sie image_input_limit_config=ImageInputLimitConfig(...), um die Imagelimits dieser Llm-Instanz für diese Anforderung außer Kraft zu setzen. Ausgelassene Felder erben die Instanzkonfiguration. Andere Schlüsselwortargumente werden mit der Provideranforderung gesendet.
• Rücksendungen: Normalisierte LLM-Ausgabe.
• Rückgabetyp: LlmResponse

Eigenschaft supports_vision

• Rückgabetyp: bool
• Beschreibung: Geben Sie an, ob dieses LLM die Bildeingabe unterstützt, und ermitteln Sie so schnell wie möglich.

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.
  • embedding_dimension int | None – Optionale Einbettungsvektordimension. Wenn angegeben, können DB-Backed-Clients Vektorgeschemas erstellen oder validieren, ohne eine Provider-Probe zu senden. Wenn embedding_dimension ausgelassen wird, wird die Dimension mit einer kleinen Fallback-Sonde faul inferenziert.
  • max_input_tokens int – Maximale Anzahl Eingabe-Token, die vom Einbettungsmodell unterstützt werden. Wenn keine Angabe gemacht wird, validiert die Eigenschaft max_input_tokens eine Provider-Sondierung auf geschätzte 512-Eingabetoken und cacht 512 als konservatives Fallback. Ein Modell-Tokenizer wird nicht lokal ausgeführt. Legen Sie daher max_input_tokens manuell basierend auf dem dokumentierten Eingabebudget des Modells fest.
  • 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.
  • document_prefix str | None – Optionales Präfix, das nur beim Einbetten von Nicht-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.
  • proxy str | None – Optionale Proxy-URL für Provideranforderungen. Wenn angegeben, hat dieser explizite Proxy Vorrang vor Proxyeinstellungen aus der Umgebung. Wenn diese Option ausgelassen wird, werden Umgebungsproxyeinstellungen verwendet, wenn trust_env aktiviert ist.
  • trust_env bool: Gibt an, ob der Provider Proxy- und TLS-Einstellungen aus Umgebungsvariablen liest. Der Standardwert ist True, wenn er ausgelassen wird. Setzen Sie diesen Wert auf False, um diese Umgebungseinstellungen zu ignorieren. Eine explizite proxy wird weiterhin verwendet.
  • key_file str | None – Optionaler Pfad zu der Private-Key-Datei des Clients im PEM-Format. Geben Sie sie zusammen mit cert_file an, wenn der Server gegenseitige TLS erfordert.
  • cert_file str | None – Optionaler Pfad zu der Clientzertifikatskettendatei im PEM-Format. Geben Sie sie zusammen mit key_file an, wenn der Server gegenseitige TLS erfordert.
  • ca_file str | None – Optionaler Pfad zu einem vertrauenswürdigen CA-Zertifikat oder -Bundle im PEM-Format, mit dem das Serverzertifikat überprüft wird. Verwenden Sie diese Option für eine private oder anderweitig nicht systembezogene CA.
  • **default_kwargs (Beliebig) – 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 und Nicht-Abfragetexte erhalten document_prefix, wenn sie konfiguriert sind.
• 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 und Nicht-Abfragetexte erhalten document_prefix, wenn sie konfiguriert sind.
• 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.

Eigenschaft embedding_dimension

• Rückgabetyp: int

• Beschreibung: Gibt die konfigurierte oder inferenzierte Einbettungsdimension zurück.

• Rückgaben: Positive Anzahl von Dimensionen in jedem Einbettungsvektor.
• Rückgabetyp: int

Hinweise

Ein vom Konstruktor angegebener Wert wird zurückgegeben, ohne den Provider zu kontaktieren. Andernfalls prüft die Eigenschaft einmal und speichert das Ergebnis im Cache.

Eigenschaft max_input_tokens

• Rückgabetyp: int

• Beschreibung: Gibt den konfigurierten oder inferenzierten Einbettungsgrenzwert für das Eingabe-Token zurück.

• Rückgaben: Die maximale Anzahl positiver Eingabe-Token für eine Text-Payload.
• Rückgabetyp: int

Hinweise

Ein vom Konstruktor angegebener Wert wird zurückgegeben, ohne den Provider zu kontaktieren. Andernfalls validiert die Eigenschaft eine Provider-Probe, deren Größe auf geschätzte 512-Eingabetoken geschätzt wird, und cacht 512 als konservatives Fallback. Ein Modell-Tokenizer wird nicht lokal ausgeführt. Legen Sie daher max_input_tokens manuell aus dem dokumentierten Eingabebudget des Modells fest, wenn die Genauigkeit wichtig ist.

Klasse oracleagentmemory.core.Reranker

Basis: IReranker

Reranker mit Provider-neutraler Rerank-Schnittstelle.

• Parameter:
  • model str – Reranker-Modell-ID. Stellen Sie OCI Generative AI-Modelle mit oci/ voran, z.B. oci/cohere.rerank-v4.0-fast.
  • api_base str | None – Optionale Basis-URL für einen OpenAI-kompatiblen Rangfolgeendpunkt.
  • api_key str | None: Optionaler API-Schlüssel, der vom Provider verwendet wird.

  • **default_kwargs (Beliebige) –

    Provider-spezifische Optionen, die auf jede Rangfolgeanforderung angewendet werden.

    Hinweis: Für das OCI-Reranking sind oci_compartment_id, oci_region, oci_user, oci_fingerprint, oci_tenancy und oci_key_file erforderlich. Installieren Sie die optionale rerank-oci-Abhängigkeitsgruppe, bevor Sie ein OCI-Modell verwenden.

Beispiele

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

Reranker mit Provider-Unterstützung erstellen

Methode rerank_async (asynchron)

Ordnen Sie Dokumente asynchron nach Relevanz für eine Abfrage ein.

• Parameter:
  • query str – Suchabfrage, mit der die Dokumente verglichen werden.
  • Dokumente list[str]: Text des Kandidatendokuments in stabiler Eingabereihenfolge.
  • **kwargs (Beliebige) – Providerspezifische Optionen, die an den Ranglistenprovider weitergeleitet werden.
• Retouren: Schließen Sie das Providerranking ab, das vom höchsten Relevanzscore bis zum niedrigsten Wert sortiert ist.
• Rückgabetyp: RerankResponse

Oracle DB-Einbettungen

Klasse oracleagentmemory.core.embedders.OracleDBEmbedder

Basis: IEmbedder

Einbetten von Text durch Aufrufen von SQL zur Einbettung in Oracle AI Database.

Durch diese Einbettung bleibt der vorhandene Einbettungsvertrag des Packages intakt, während die Einbettungsgenerierung über SQL an die Datenbank delegiert wird. Die direkte Einbettung bevorzugt VECTOR_EMBEDDING für datenbankresidente Modellkonfigurationen und fällt zurück auf DBMS_VECTOR_CHAIN.UTL_TO_EMBEDDING, wenn die Vectorizer-Konfiguration die Oberfläche des JSON-Providerparameters benötigt.

Erstellen Sie einen Einbettungsknoten, der von der SQL-Ausführung von Oracle AI Database unterstützt wird.

• Parameter:
  • Verbindung object: Oracle DB-Verbindung oder poolähnliches Objekt mit einer aufrufbaren cursor()- oder acquire()-Methode.
  • model str: Modell-ID. Bei dem Standardprovider "database" muss es sich um eine nicht mit Anführungszeichen versehene Oracle SQL-ID oder eine Schema-qualifizierte ID für ein datenbankinternes Einbettungsmodell handeln. Das verbundene Schema muss diesen Modellnamen in SQL auflösen können. Verwenden Sie für einen Remoteprovider den Modellnamen oder die anbieterspezifische Modell-ID, die von diesem Service erwartet wird.
  • input_name str: Modell-Eingabename, der von VECTOR_EMBEDDING verwendet wird, wenn die Vectorizer-Konfiguration auf ein datenbankresidentes Modell ausgerichtet ist. Der Standardwert ist "DATA", der Eingabename, der von den Beispielen und Metadaten des Einbettungsmodells DBMS_VECTOR ONNX von Oracle verwendet wird. Übergeben Sie den tatsächlichen Modelleingabenamen hier, wenn das importierte Modell ein anderes Attribut verwendet.
  • embedding_dimension int | None – Optionale Einbettungsvektordimension. Wenn angegeben, können DB-Backed-Clients Vektorgeschemas erstellen oder validieren, ohne eine Dimension-Probe-Abfrage zu senden. Wenn sie weggelassen wird, wird die Dimension mit einer Anforderung zur Einbettung einer Sonde träge abgeleitet.
  • max_input_tokens int: Maximales Eingabe-Token-Budget, das vom Standardspeicher-Chunker verwendet wird. Wenn keine Angabe gemacht wird, validiert die Eigenschaft max_input_tokens eine Datenbankmodell-Sondierung in der Größe auf geschätzte 512-Eingabetoken und cacht 512 als konservatives Fallback. Ein Modell-Tokenizer wird nicht lokal ausgeführt. Legen Sie daher max_input_tokens manuell basierend auf dem dokumentierten Eingabebudget des Modells fest.
  • normalisieren bool – Gibt an, ob Einbettungen nach dem Abrufen aus der Datenbank L2-normalisiert werden sollen.
  • query_prefix str | None – Optionales Präfix, das nur beim Einbetten von Abfragetexten hinzugefügt wird.
  • batch_size int: Maximale Anzahl von Texten, die in einem SQL-Einbettungs-Roundtrip gruppiert sind.
  • Provider str: Einbettungsprovider, der in Oracle AI Database konfiguriert ist. Der Standardwert "database" verwendet ein Einbettungsmodell, das in Oracle Database geladen wird, in der Regel im ONNX-Format. Remote-Provider umfassen Services wie Cohere, OpenAI, Google AI und Oracle Cloud Infrastructure Generative AI. OpenAI-kompatible Services wie vLLM verwenden "openai" zusammen mit dem Serviceendpunkt in provider_options. Informationen zu unterstützten Providern und deren Konfiguration finden Sie in der Dokumentation zu DBMS_VECTOR_CHAIN von Oracle: https://docs.oracle.com/en/database/oracle/oracle-database/26/vecse/dbms_vector_chain-vecse.html
  • provider_options Mapping[str, Any] | None – Optionale Oracle Vectorizer-Einstellungen, wie url, credential_name oder host="local". Konstruktorargumente setzen in dieser Zuordnung provider, model und input_name außer Kraft. Optionen des Oracle-Dokumentproviders und das Erstellen von Datenbankzugangsdaten unter: 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

Beispiele

Verwenden Sie einen Oracle-Verbindungspool und ein DB-residentes Einbettungsmodell:

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

Schema-qualifizierte Modellnamen können verwendet werden, wenn das verbundene Schema über Berechtigungen für ein Modell verfügt, das einem anderen Schema gehört:

shared_embedder = OracleDBEmbedder(
    connection=pool,
    model="MY_OTHER_SCHEMA.MY_ONNX_MODEL",
    embedding_dimension=768,
)
shared_embedder.embed(["hello world"])

Die folgenden Beispiele zeigen, wie Sie Oracle AI Database-Einbettungen mit OpenAI, vLLM, Cohere und anderen Anbietern konfigurieren:

OpenAI-Beispiel:

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-Beispiel:

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-kompatible Services wie vLLM verwenden auch den "openai"-Provider. Setzen Sie host auf "local", wenn der Endpunkt keine Oracle AI Database-Zugangsdaten benötigt:

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

Zwillingsbeispiel:

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

Beispiel für 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"])

Abfragespezifische Präfixe können ohne Änderung der Speicher-API konfiguriert werden:

embedder = OracleDBEmbedder(
    connection=pool,
    model="DOC_MODEL",
    query_prefix="search_document: ",
)
embedder.embed(["pizza"], is_query=True)

Methode embed

Integrieren Sie einen Textbatch, indem Sie SQL in Oracle AI Database ausführen.

• 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 einer Zeile pro Eingabetext.
• Rückgabetyp: numpy.ndarray

Beispiele

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

Methode embed_async (asynchron)

Mit Oracle AI Database SQL asynchron einen Textbatch einbetten.

• 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 einer Zeile pro Eingabetext.
• Rückgabetyp: numpy.ndarray

Beispiele

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

Eigenschaft embedding_dimension

• Rückgabetyp: int

• Beschreibung: Gibt die konfigurierte oder inferenzierte Einbettungsdimension zurück.

• Rückgaben: Positive Anzahl von Dimensionen in jedem Einbettungsvektor.
• Rückgabetyp: int

Hinweise

Ein vom Konstruktor bereitgestellter Wert wird zurückgegeben, ohne das Datenbankmodell zu kontaktieren. Andernfalls prüft die Eigenschaft einmal und speichert das Ergebnis für zukünftige Zugriffe im Cache.

Beispiele

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

Methode get_vectorizer_config_json

Geben Sie JSON für die Oracle Vectorizer-Voreinstellung für dieses DB-Modell zurück.

Dieselbe Modellkonfiguration wird durch direkte Einbettung und durch verwaltete Hybridindizes verwendet. Die direkte Einbettung verwendet sie, um zu entscheiden, ob VECTOR_EMBEDDING das konfigurierte Datenbankmodell darstellen kann oder ob DBMS_VECTOR_CHAIN.UTL_TO_EMBEDDING für Provider-JSON erforderlich ist. Die Hybridindizierung übergibt sie an DBMS_VECTOR_CHAIN.CREATE_PREFERENCE, und dann ist die Vectorizer-Pipeline von Oracle Eigentümer der Einbettungsarbeit für diesen Index.

• Rückgaben: Kompakte JSON-Payload für DBMS_VECTOR_CHAIN.CREATE_PREFERENCE mit DBMS_VECTOR_CHAIN.VECTORIZER.
• Rückgabetyp: str

Beispiele

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

Eigenschaft max_input_tokens

• Rückgabetyp: int

• Beschreibung: Gibt das konfigurierte oder inferenzierte Input-Token-Budget für das Chunking zurück.

• Rückgaben: Die maximale Anzahl positiver Eingabe-Token für eine Text-Payload.
• Rückgabetyp: int

Hinweise

Ein vom Konstruktor bereitgestellter Wert wird zurückgegeben, ohne das Datenbankmodell zu kontaktieren. Andernfalls validiert die Eigenschaft eine Datenbankmodell-Sondierung in der Größe auf geschätzte 512-Eingabetoken und cacht 512 als konservatives Fallback. Ein Modell-Tokenizer wird nicht lokal ausgeführt. Legen Sie daher max_input_tokens manuell aus dem dokumentierten Eingabebudget des Modells fest, wenn die Genauigkeit wichtig ist.

Beispiele

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