GML et intégrateurs

Cette page présente les interfaces abstraites utilisées pour connecter les LLM et les intégrateurs à la mémoire d'Oracle Agent.

Interface LLM

classe oracleagentmemory.apis.llms.ILlm

Bases : ABC

Interface abstraite pour l'appel du GML.

méthode generate (résumé)

Générer une réponse à partir d'un GML de manière synchrone.

• Paramètres :
  • prompt str | Sequence[dict[str, str]] – Invite de texte brut (traité en tant que message d'utilisateur unique) ou liste de messages de type clavardage, chaque message étant un mappage avec au moins une clé "content" et éventuellement une clé "role".
  • response_json_schema dict[str, Any] | None – Schéma JSON facultatif décrivant le format de réponse attendu.
  • **kwargs (Au choix) – Arguments de mot clé propres au fournisseur transmis au serveur dorsal sous-jacent.
• Retours : Sortie du LLM normalisé.
• Type de retour : LlmResponse

méthode generate_async (abstrait, asynchrone)

Générer une réponse de façon asynchrone à partir d'un GML.

• Paramètres :
  • prompt str | Sequence[dict[str, str]] – Invite de texte brut (traité en tant que message d'utilisateur unique) ou liste de messages de type clavardage, chaque message étant un mappage avec au moins une clé "content" et éventuellement une clé "role".
  • response_json_schema dict[str, Any] | None – Schéma JSON facultatif décrivant le format de réponse attendu.
  • **kwargs (Au choix) – Arguments de mot clé propres au fournisseur transmis au serveur dorsal sous-jacent.
• Retours : Sortie du LLM normalisé.
• Type de retour : LlmResponse

Réponses pour le GML

classe oracleagentmemory.apis.llms.LlmResponse

Bases : object

Une petite réponse normalisée retournée par ILlm.

• Paramètres : texte str

text

Contenu textuel généré principal.

• Type : str

Interface d'intégration

classe oracleagentmemory.apis.IEmbedder

Bases : ABC

Interface abstraite pour les intégrateurs de texte.

méthode embed (résumé)

Intégrez un lot de textes dans un tableau 2D float32 NumPy.

• Paramètres :
  • textes list[str] – Lot de textes à intégrer.
  • is_query bool – Indique si le lot est intégré pour l'extraction au moment de l'interrogation.
• Retours : Un tableau 2D en forme de (len(texts), dim) avec dtype=float32.
• Type de retour : numpy.ndarray

méthode embed_async (abstrait, asynchrone)

Intégrez un lot de textes dans un tableau 2D float32 NumPy.

• Paramètres :
  • textes list[str] – Lot de textes à intégrer.
  • is_query bool – Indique si le lot est intégré pour l'extraction au moment de l'interrogation.
• Retours : Un tableau 2D en forme de (len(texts), dim) avec dtype=float32.
• Type de retour : numpy.ndarray

Adaptateurs LiteLLM

classe oracleagentmemory.core.llms.LlmApiType

Bases : str, Enum

Familles d'API compatibles avec OpenAI prises en charge pour Llm.

CHAT_COMPLETIONS *= 'CHAT_COMPLETIONS'*

RÉPONSES *= 'réponses'*

classe oracleagentmemory.core.llms.Llm

Bases : ILlm

Adaptateur pour générer des réponses de modèle.

Créez un adaptateur LLM.

• Paramètres :
  • modèle str – Identificateur de modèle envoyé au fournisseur de modèle sous-jacent.
  • api_base str | None – URL de base facultative pour un point d'extrémité compatible OpenAI.
  • api_key str | None – Clé d'API facultative utilisée lors de la communication avec le fournisseur.
  • api_type LlmApiType – Famille d'API à appeler. Utilisez LlmApiType.CHAT_COMPLETIONS pour les achèvements de clavardage ou LlmApiType.RESPONSES pour l'API des réponses. La valeur par défaut est LlmApiType.CHAT_COMPLETIONS.
  • stream bool – Indique s'il faut demander la sortie de diffusion en continu. Le flux est consommé en interne et retourné en tant que LlmResponse unique.
  • température float | None – Température d'échantillonnage facultative.
  • max_tokens int | None – Limite facultative du jeton de sortie. Avec api_type=LlmApiType.CHAT_COMPLETIONS, ce message est envoyé en tant que max_tokens. Avec api_type=LlmApiType.RESPONSES, ce message est envoyé en tant que max_output_tokens.
  • reasoning_effort str | None – Effort de raisonnement facultatif. Avec api_type=LlmApiType.CHAT_COMPLETIONS, ce message est envoyé en tant que reasoning_effort. Avec api_type=LlmApiType.RESPONSES, cette valeur est convertie en reasoning={"effort": ...}.
  • **default_kwargs (Au choix) - Arguments avancés de mot clé par défaut appliqués à chaque appel. Préférez les paramètres explicites ci-dessus pour les paramètres de connexion et de génération communs. Lorsque le même paramètre est fourni explicitement et dans default_kwargs, le paramètre explicite est prioritaire.

Exemples

Les modèles du service d'intelligence artificielle générative pour OCI utilisent les identificateurs de modèle "oci/..." de LiteLLM. Une configuration commune consiste à transmettre les détails d'authentification de clé d'API OCI à partir du fichier de configuration OCI standard au moyen d'arguments de mot clé propres à LiteLLM. La trousse SDK Python pour OCI n'est pas installée par cet ensemble; les applications qui en dépendent déjà peuvent également transmettre un objet 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.")

Les modèles hébergés par OpenAI utilisent des identificateurs de modèle LiteLLM tels que "openai/gpt-5.1" et une clé d'API OpenAI. Les achèvements de clavardage constituent la famille d'API par défaut.

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

Utilisez api_type=LlmApiType.RESPONSES lorsque le modèle cible doit être appelé au moyen de l'API de réponses OpenAI au lieu des fins de clavardage.

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'

Les serveurs compatibles OpenAI auto-hébergés, y compris vLLM, sont appelés avec un identificateur de modèle "openai/..." plus l'URL de base /v1 du serveur. Transmettez un api_key nominal tel que "none" lorsque le point d'extrémité n'applique pas l'authentification.

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

méthode generate

Générer une réponse.

• Paramètres :
  • prompt str | Sequence[dict[str, str]] – Messages de chaîne d'invite ou de clavardage. Une chaîne est traitée comme un message utilisateur unique.
  • response_json_schema dict[str, Any] | None – Schéma JSON facultatif décrivant le format de réponse attendu. Lorsqu'elle est fournie, cette méthode utilise le mécanisme de sortie structurée natif du fournisseur via response_format compatible OpenAI.
  • **kwargs (Au choix) - Paramètres d'appel supplémentaires envoyés avec cette demande. Transmettez api_type=LlmApiType.RESPONSES pour acheminer cet appel au moyen de l'API Réponses.
• Retours : Sortie du LLM normalisé.
• Type de retour : LlmResponse

méthode generate_async (asynchrone)

Générer une réponse de manière asynchrone.

• Paramètres :
  • prompt str | Sequence[dict[str, str]] – Messages de chaîne d'invite ou de clavardage. Une chaîne est traitée comme un message utilisateur unique.
  • response_json_schema dict[str, Any] | None – Schéma JSON facultatif décrivant le format de réponse attendu. Lorsqu'elle est fournie, cette méthode utilise le mécanisme de sortie structurée natif du fournisseur via response_format compatible OpenAI.
  • **kwargs (Au choix) - Paramètres d'appel supplémentaires envoyés avec cette demande. Transmettez api_type=LlmApiType.RESPONSES pour acheminer cet appel au moyen de l'API Réponses.
• Retours : Sortie du LLM normalisé.
• Type de retour : LlmResponse

classe oracleagentmemory.core.embedders.Embedder

Bases : IEmbedder

Intégrateur soutenu par le fournisseur.

Créer un intégrateur soutenu par un fournisseur.

• Paramètres :
  • modèle str – Identificateur de modèle envoyé au fournisseur d'intégration sous-jacent.
  • api_base str | None – URL de base facultative pour un point d'extrémité compatible OpenAI.
  • api_key str | None – Clé d'API facultative utilisée lors de la communication avec le fournisseur.
  • normalize (Normaliser) bool – Indique si les intégrations retournées par le fournisseur doivent être normalisées à L2.
  • query_prefix str | None – Préfixe facultatif ajouté uniquement lors de l'intégration de textes d'interrogation.
  • truncate_prompt_tokens int | None – Limite facultative du jeton d'entrée transmise aux fournisseurs qui prennent en charge la troncature des invites d'intégration longues.
  • **default_kwargs (Au choix) - Arguments avancés de mot clé par défaut appliqués à chaque appel d'intégration. Préférez les paramètres explicites ci-dessus pour les paramètres communs.

Exemples

Les modèles d'intégration du service d'intelligence artificielle générative pour OCI utilisent des identificateurs de modèle "oci/...". Une configuration commune consiste à transmettre les détails d'authentification de clé d'API OCI à partir du fichier de configuration OCI standard au moyen d'arguments de mot clé propres à LiteLLM. La trousse SDK Python pour OCI n'est pas installée par cet ensemble; les applications qui en dépendent déjà peuvent également transmettre un objet 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"])

Les modèles d'intégration hébergés par OpenAI utilisent des identificateurs tels que "openai/text-embedding-3-small" avec une clé d'API OpenAI.

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

Les serveurs d'intégration compatibles OpenAI auto-hébergés, y compris vLLM, utilisent le préfixe du fournisseur "hosted_vllm/..." avec l'URL de base /v1 du serveur.

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

méthode embed

Intégrer un lot de textes à l'aide du fournisseur configuré.

• Paramètres :
  • textes list[str] – Lot de chaînes de texte brut à intégrer.
  • is_query bool – Indique si le texte est une interrogation. Les textes d'interrogation reçoivent query_prefix lorsqu'un texte a été configuré.
• Retours : Matrice float32 bidimensionnelle avec les vecteurs d'intégration retournés par le fournisseur.
• Type de retour : numpy.ndarray
• Lances : RuntimeError - Si les données utiles de la réponse du fournisseur n'incluent pas l'intégration de données.

méthode embed_async (asynchrone)

Intégrez de manière asynchrone un lot de textes à l'aide du fournisseur configuré.

• Paramètres :
  • textes list[str] – Lot de chaînes de texte brut à intégrer.
  • is_query bool – Indique si le texte est une interrogation. Les textes d'interrogation reçoivent query_prefix lorsqu'un texte a été configuré.
• Retours : Matrice float32 bidimensionnelle avec les vecteurs d'intégration retournés par le fournisseur.
• Type de retour : numpy.ndarray
• Lances : RuntimeError - Si les données utiles de la réponse du fournisseur n'incluent pas l'intégration de données.