LLM et embarqueurs

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

Interface LLM

classe oracleagentmemory.apis.llms.ILlm

Bases : ABC

Interface abstraite pour l'appel LLM.

method generate (résumé)

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

• Paramètres:
  • invite str | Sequence[dict[str, str]] : invite en texte brut (traité en tant que message utilisateur unique) ou liste de messages de type discussion, où chaque message est un mapping 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 (N'importe lequel) : arguments de mot-clé propres au fournisseur transmis au back-end sous-jacent.
• Renvoie : sortie LLM normalisée.
• Type de retour : LlmResponse

méthode generate_async (abstrait, asynchrone)

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

• Paramètres:
  • invite str | Sequence[dict[str, str]] : invite en texte brut (traité en tant que message utilisateur unique) ou liste de messages de type discussion, où chaque message est une correspondance avec au moins une clé "content" et éventuellement une valeur "role".
  • response_json_schema dict[str, Any] | None : schéma JSON facultatif décrivant le format de réponse attendu.
  • **kwargs (N'importe lequel) : arguments de mot-clé propres au fournisseur transmis au back-end sous-jacent.
• Renvoie : sortie LLM normalisée.
• Type de retour : LlmResponse

Réponses LLM

classe oracleagentmemory.apis.llms.LlmResponse

Bases : object

Petite réponse normalisée renvoyée par ILlm.

• Paramètres : text str

Texte

Contenu de texte généré principal.

• Type : str

Interface Embedder

classe oracleagentmemory.apis.IEmbedder

Bases : ABC

Interface abstraite pour les intégrateurs de texte.

method 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 batch est imbriqué pour l'extraction au moment de la requête.
• Retours : 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 batch est imbriqué pour l'extraction au moment de la requête.
• Retours : 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 OpenAI prises en charge pour Llm.

CHAT_COMPLETIONS *= 'CHAT_COMPLETIONS'*

RÉPONSES *= 'réponses'*

classe oracleagentmemory.core.llms.Llm

Bases : ILlm

Adaptateur pour la génération de réponses de modèle.

Créez un adaptateur LLM.

• Paramètres:
  • model str : identificateur de modèle envoyé au fournisseur de modèle sous-jacent.
  • api_base str | None : URL de base facultative pour une adresse compatible OpenAI.
  • api_key str | None : clé d'API facultative utilisée lorsque vous contactez le fournisseur.
  • api_type LlmApiType : famille d'API à appeler. Utilisez LlmApiType.CHAT_COMPLETIONS pour les fins de discussion 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 une sortie de transmission en continu. Le flux est consommé en interne et renvoyé en tant qu'élément LlmResponse unique.
  • temperature float | None – Température d'échantillonnage facultative.
  • max_tokens int | None : limite de jeton de sortie facultative. Avec api_type=LlmApiType.CHAT_COMPLETIONS, il est envoyé en tant que max_tokens. Avec api_type=LlmApiType.RESPONSES, il est envoyé en tant que max_output_tokens.
  • reasoning_effort str | None : effort de raisonnement facultatif. Avec api_type=LlmApiType.CHAT_COMPLETIONS, il est envoyé en tant que reasoning_effort. Avec api_type=LlmApiType.RESPONSES, elle est convertie en reasoning={"effort": ...}.
  • **default_kwargs (Any) : arguments de mot-clé par défaut avancés 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 OCI Generative AI 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 via des arguments de mot-clé propres à LiteLLM. Le kit SDK OCI Python n'est pas installé par ce package. 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 fins de discussion sont 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é via l'API de réponses OpenAI au lieu d'effectuer des discussions.

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 une valeur api_key nominale telle que "none" lorsque l'adresse 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]] – Invite de chaîne ou de messages de discussion. 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 avec OpenAI.
  • **kwargs (N'importe lequel) – Paramètres d'appel supplémentaires envoyés avec cette demande. Transmettez api_type=LlmApiType.RESPONSES pour acheminer cet appel via l'API des réponses.
• Renvoie : sortie LLM normalisée.
• Type de retour : LlmResponse

method generate_async (async)

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

• Paramètres:
  • prompt str | Sequence[dict[str, str]] – Invite de chaîne ou de messages de discussion. 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 avec OpenAI.
  • **kwargs (N'importe lequel) – Paramètres d'appel supplémentaires envoyés avec cette demande. Transmettez api_type=LlmApiType.RESPONSES pour acheminer cet appel via l'API des réponses.
• Renvoie : sortie LLM normalisée.
• Type de retour : LlmResponse

classe oracleagentmemory.core.embedders.Embedder

Bases : IEmbedder

Intégration soutenue par le fournisseur.

Créez un intégrateur soutenu par le fournisseur.

• Paramètres:
  • model str : identificateur de modèle envoyé au fournisseur d'intégration sous-jacent.
  • api_base str | None : URL de base facultative pour une adresse compatible OpenAI.
  • api_key str | None : clé d'API facultative utilisée lorsque vous contactez le fournisseur.
  • normalize bool : indique si les intégrations L2 doivent être normalisées et renvoyées par le fournisseur.
  • query_prefix str | None : préfixe facultatif ajouté uniquement lors de l'intégration de textes de requête.
  • truncate_prompt_tokens int | None – Limite de jetons d'entrée facultative transmise aux fournisseurs qui prennent en charge la troncature des longues invites d'intégration.
  • **default_kwargs (Any) : arguments de mot-clé par défaut avancés 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 OCI Generative AI 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 via des arguments de mot-clé propres à LiteLLM. Le kit SDK OCI Python n'est pas installé par ce package. 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 de 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égrez 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 requête. Les textes de requête reçoivent query_prefix lorsqu'un texte a été configuré.
• Retours : matrice float32 bidimensionnelle avec les vecteurs d'intégration renvoyés par le fournisseur.
• Type de retour : numpy.ndarray
• Elèves : RuntimeError – Si la charge utile de réponse du fournisseur n'inclut pas les données d'intégration.

method embed_async (async)

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 requête. Les textes de requête reçoivent query_prefix lorsqu'un texte a été configuré.
• Retours : matrice float32 bidimensionnelle avec les vecteurs d'intégration renvoyés par le fournisseur.
• Type de retour : numpy.ndarray
• Elèves : RuntimeError – Si la charge utile de réponse du fournisseur n'inclut pas les données d'intégration.