LLM, embarqueurs et classeurs

Cette page présente les interfaces abstraites utilisées pour connecter les LLM, les intégrateurs et les classeurs à nouveau dans 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:
- prompt str | Sequence[Message | Mapping[str, str | Sequence[Mapping[str, Any]]]] | ChatMessageTypedDictT : chaîne, séquence de dictionnaire de style discussion ou séquence d'objets Message. Les chaînes deviennent des messages utilisateur. Le contenu des messages peut inclure des parties de texte et d'image. Les pièces d'image sont validées avant d'être envoyées au fournisseur.
- response_json_schema dict[str, Any] | None : schéma JSON facultatif décrivant le format de réponse attendu.
- **kwargs (N'importe lequel) – Options d'appel supplémentaires. Llm intégré accepte api_type=LlmApiType.RESPONSES pour sélectionner l'API des réponses et image_input_limit_config=ImageInputLimitConfig(...) pour remplacer les limites d'image pour cette demande. D'autres arguments de mot-clé sont 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:
- prompt str | Sequence[Message | Mapping[str, str | Sequence[Mapping[str, Any]]]] | ChatMessageTypedDictT : chaîne, séquence de dictionnaire de style discussion ou séquence d'objets Message. Les chaînes deviennent des messages utilisateur. Le contenu des messages peut inclure des parties de texte et d'image. Les pièces d'image sont validées avant d'être envoyées au fournisseur.
- response_json_schema dict[str, Any] | None : schéma JSON facultatif décrivant le format de réponse attendu.
- **kwargs (N'importe lequel) – Options d'appel supplémentaires. Llm intégré accepte api_type=LlmApiType.RESPONSES pour sélectionner l'API des réponses et image_input_limit_config=ImageInputLimitConfig(...) pour remplacer les limites d'image pour cette demande. D'autres arguments de mot-clé sont 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

Une 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

propriété `embedding_dimension`

Type de retour : int
Description : renvoie la taille des incorporations produites par ce programme.

Les sous-classes peuvent remplacer cette propriété lorsque la largeur d'intégration est connue à partir des métadonnées de configuration ou de fournisseur. L'implémentation par défaut teste embed() une fois et met en cache la taille du résultat.

Retours : nombre positif de valeurs à virgule flottante dans chaque vecteur d'intégration.
Type de retour : int

propriété `max_input_tokens`

Type de retour : int
Description : renvoie le nombre maximal de jetons d'entrée pris en charge.

Les sous-classes peuvent remplacer cette propriété lorsque le budget d'entrée du modèle est connu à partir des métadonnées de configuration ou de fournisseur. L'implémentation par défaut valide une sonde dimensionnée en jetons d'entrée 512 estimés une fois et met en cache 512 en tant que solution de secours conservatrice. Il n'exécute pas un tokenizer de modèle localement, les appelants doivent donc définir max_input_tokens manuellement lorsque le budget d'entrée réel du modèle est connu.

Retours : nombre maximum positif de jetons d'entrée pour une charge utile de texte.
Type de retour : int

Interface Reranker

classe `oracleagentmemory.apis.IReranker`

Bases : ABC

Interface abstraite pour le reclassement de documents synchrone et asynchrone.

Les implémentations doivent renvoyer un résultat pour chaque document d'entrée. Chaque index d'entrée basé sur zéro doit apparaître exactement une fois. relevance_score doit être fini et des scores plus élevés doivent indiquer une plus grande pertinence. Les résultats doivent être triés du score le plus élevé au score le plus bas.

méthode `rerank`

Classez les documents de manière synchrone en les déléguant à rerank_async.

Paramètres:
- query str – Requête de recherche utilisée pour comparer les documents.
- documents list[str] – Texte du document candidat dans un ordre d'entrée stable. Les index de résultats font référence aux postes de cette liste.
- **kwargs (N'importe lequel) – Options propres au fournisseur.
Retours : classement complet avec exactement len(documents) résultats. Chaque index d'entrée apparaît une seule fois, du plus pertinent au moins pertinent.
Type de retour : RerankResponse

méthode `rerank_async` (abstrait, asynchrone)

Classement asynchrone des documents par pertinence pour une requête.

Paramètres:
- query str – Requête de recherche utilisée pour comparer les documents.
- documents list[str] – Texte du document candidat dans un ordre d'entrée stable. Les index de résultats font référence aux postes de cette liste.
- **kwargs (N'importe lequel) – Options propres au fournisseur.
Retours : classement complet avec exactement len(documents) résultats. Chaque index d'entrée apparaît une seule fois, du plus pertinent au moins pertinent.
Type de retour : RerankResponse

classe `oracleagentmemory.apis.RerankResponse`

Bases : object

Classement complet des documents, trié par score de pertinence décroissant.

Paramètres : résultats list[RerankResponseResult]

classe `oracleagentmemory.apis.RerankResponseResult`

Bases : object

Résultat de reclassement d'un document.

Paramètres:
- index int : position zéro du document dans la liste d'entrée.
- relevance_score float – Score de pertinence pour la paire requête-document. Des valeurs plus élevées signifient une plus grande pertinence.
- document str | None – Texte du document lorsque le fournisseur l'a renvoyé, sinon None.

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.
- 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": ...}.
- enable_structured_output_reminder bool : permet d'ajouter un schéma de sortie structurée à l'invite lorsque la sortie structurée est demandée. Si elle est omise, la valeur par défaut suit la route de modèle : elle est activée pour les modèles vLLM hébergés et non fermés sur la route "openai/..." explicite de LiteLLM. Définissez-le explicitement pour les noms de modèle Bare ou d'autres adresses personnalisées.
- supports_vision bool – Indique si ce modèle accepte le contenu d'image dans les invites de génération. Lorsqu'elle est omise, la prise en charge est détectée paresseusement : l'adaptateur vérifie d'abord les métadonnées du modèle et, lorsque les métadonnées ne sont pas disponibles, envoie une sonde d'image rouge fixe. Définissez cette valeur sur True ou False pour ignorer la détection.
- image_input_limit_config ImageInputLimitConfig : limites d'image brute et d'image par demande facultatives. Les champs omis utilisent les valeurs par défaut du kit SDK. La validation reste activée pour chaque demande d'image.
- max_concurrent_requests int | None : nombre maximal de demandes asynchrones autorisées via cette instance de LLM. Omettez la valeur pour utiliser 16. Transmettez None pour désactiver la limitation de la simultanéité. Définissez-le explicitement lorsque l'adresse a besoin d'un comportement différent.
- proxy str | None : URL de proxy facultative pour les demandes de fournisseur. Lorsqu'il est fourni, ce proxy explicite est prioritaire sur les paramètres de proxy de l'environnement. En cas d'omission, les paramètres de proxy d'environnement sont utilisés lorsque trust_env est activé.
- trust_env bool – Indique si le fournisseur demande des paramètres de proxy de lecture et TLS à partir des variables d'environnement. La valeur par défaut est True lorsqu'elle est omise. Définissez la valeur sur False pour ignorer ces paramètres d'environnement ; une valeur proxy explicite est toujours utilisée.
- key_file str | None : chemin facultatif vers le fichier de clés privées client au format PEM. Fournissez-le avec cert_file lorsque le serveur requiert un protocole TLS mutuel.
- cert_file str | None : chemin facultatif vers le fichier de chaîne de certificat client au format PEM. Fournissez-le avec key_file lorsque le serveur requiert un protocole TLS mutuel.
- ca_file str | None : chemin facultatif vers un certificat ou un bundle d'autorité de certification de confiance au format PEM utilisé pour vérifier le certificat de serveur. Utilisez-le pour une CA privée ou autre que système.
- **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[Message | Mapping[str, str | Sequence[Mapping[str, Any]]]] | ChatMessageTypedDictT : chaîne, séquence de dictionnaire de style discussion ou séquence d'objets Message. Les chaînes deviennent des messages utilisateur. Le contenu peut inclure des parties de texte et d'image. Les pièces d'image sont validées avant d'être envoyées au fournisseur.
- 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 (Any) – Paramètres d'appel supplémentaires. Transmettez api_type=LlmApiType.RESPONSES pour acheminer cet appel via l'API des réponses. Pour les invites d'image, transmettez image_input_limit_config=ImageInputLimitConfig(...) pour remplacer les limites d'image de cette instance Llm pour cette demande ; les champs omis héritent de la configuration d'instance. D'autres arguments de mot-clé sont envoyés avec la demande de fournisseur.
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[Message | Mapping[str, str | Sequence[Mapping[str, Any]]]] | ChatMessageTypedDictT : séquence de messages de type chaîne, invite ou discussion. Les chaînes deviennent des messages utilisateur. Le contenu peut inclure des parties de texte et d'image. Les pièces d'image sont validées avant d'être envoyées au fournisseur.
- 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 (Any) – Paramètres d'appel supplémentaires. Transmettez api_type=LlmApiType.RESPONSES pour acheminer cet appel via l'API des réponses. Pour les invites d'image, transmettez image_input_limit_config=ImageInputLimitConfig(...) pour remplacer les limites d'image de cette instance Llm pour cette demande ; les champs omis héritent de la configuration d'instance. D'autres arguments de mot-clé sont envoyés avec la demande de fournisseur.
Renvoie : sortie LLM normalisée.
Type de retour : LlmResponse

propriété `supports_vision`

Type de retour : booléen
Description : indiquez si ce LLM prend en charge l'entrée d'image, en détectant paresseusement.

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.
- embedding_dimension int | None : dimension vectorielle d'intégration facultative. Lorsqu'ils sont fournis, les clients soutenus par la base de données peuvent créer ou valider des schémas vectoriels sans envoyer de sonde de fournisseur. Lorsqu'elle est omise, embedding_dimension infère la dimension paresseusement avec une petite sonde de repli.
- max_input_tokens int – Nombre maximal de jetons d'entrée pris en charge par le modèle d'intégration. Lorsqu'elle est omise, la propriété max_input_tokens valide une sonde de fournisseur dimensionnée en jetons d'entrée 512 estimés et met en cache 512 en tant que solution de secours conservatrice. Elle n'exécute pas un tokenizer de modèle localement. Par conséquent, définissez max_input_tokens manuellement en fonction du budget d'entrée documenté du modèle.
- 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.
- document_prefix str | None : préfixe facultatif ajouté uniquement lors de l'incorporation de textes autres que des requêtes.
- 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.
- proxy str | None : URL de proxy facultative pour les demandes de fournisseur. Lorsqu'il est fourni, ce proxy explicite est prioritaire sur les paramètres de proxy de l'environnement. En cas d'omission, les paramètres de proxy d'environnement sont utilisés lorsque trust_env est activé.
- trust_env bool – Indique si le fournisseur demande des paramètres de proxy de lecture et TLS à partir des variables d'environnement. La valeur par défaut est True lorsqu'elle est omise. Définissez la valeur sur False pour ignorer ces paramètres d'environnement ; une valeur proxy explicite est toujours utilisée.
- key_file str | None : chemin facultatif vers le fichier de clés privées client au format PEM. Fournissez-le avec cert_file lorsque le serveur requiert un protocole TLS mutuel.
- cert_file str | None : chemin facultatif vers le fichier de chaîne de certificat client au format PEM. Fournissez-le avec key_file lorsque le serveur requiert un protocole TLS mutuel.
- ca_file str | None : chemin facultatif vers un certificat ou un bundle d'autorité de certification de confiance au format PEM utilisé pour vérifier le certificat de serveur. Utilisez-le pour une CA privée ou autre que système.
- **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 et les textes non de requête reçoivent document_prefix lorsqu'ils sont configurés.
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 et les textes non de requête reçoivent document_prefix lorsqu'ils sont configurés.
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.

propriété `embedding_dimension`

Type de retour : int
Description : renvoie la dimension d'intégration configurée ou inférée.
Renvoie : nombre positif de dimensions dans chaque vecteur d'intégration.
Type de retour : int

Notes

Une valeur fournie par le constructeur est renvoyée sans contact avec le fournisseur. Sinon, la propriété effectue un test une fois et met en cache le résultat.

propriété `max_input_tokens`

Type de retour : int
Description : renvoie la limite de jetons d'entrée d'intégration configurée ou inférée.
Retours : nombre maximum positif de jetons d'entrée pour une charge utile de texte.
Type de retour : int

Notes

Une valeur fournie par le constructeur est renvoyée sans contact avec le fournisseur. Sinon, la propriété valide une sonde de fournisseur dimensionnée en jetons d'entrée 512 estimés et met en cache 512 en tant que restauration conservatrice. Il n'exécute pas un tokenizer de modèle localement. Par conséquent, définissez max_input_tokens manuellement à partir du budget d'entrée documenté du modèle lorsque la précision est importante.

classe `oracleagentmemory.core.Reranker`

Bases : IReranker

Reranker soutenu par une interface de reranker neutre pour le fournisseur.

Paramètres:
- model str : identificateur de modèle Reranker. Préfixez les modèles OCI Generative AI avec oci/, par exemple oci/cohere.rerank-v4.0-fast.
- api_base str | None : URL de base facultative pour une adresse de reclassement compatible OpenAI.
- api_key str | None : clé d'API facultative utilisée par le fournisseur.
- **default_kwargs (N'importe lequel) –
  
  Options spécifiques au soignant appliquées à chaque demande de reclassement.
  
  Remarque : le reclassement OCI nécessite oci_compartment_id, oci_region, oci_user, oci_fingerprint, oci_tenancy et oci_key_file. Installez le groupe de dépendances rerank-oci facultatif avant d'utiliser un modèle OCI.

Exemples

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

Créez un reranker soutenu par le fournisseur.

method `rerank_async` (async)

Classement asynchrone des documents par pertinence pour une requête.

Paramètres:
- query str – Requête de recherche utilisée pour comparer les documents.
- documents list[str] – Texte du document candidat dans un ordre d'entrée stable.
- **kwargs (N'importe lequel) – Options spécifiques au fournisseur transmises au fournisseur de reclassement.
Retours : classement complet des fournisseurs, du score de pertinence le plus élevé au score le plus bas.
Type de retour : RerankResponse

Oracle DB Embedders

classe `oracleagentmemory.core.embedders.OracleDBEmbedder`

Bases : IEmbedder

Intégrez du texte en appelant l'intégration SQL d'Oracle AI Database.

Cet outil d'intégration conserve intact le contrat d'intégration existant du package tout en déléguant la génération de l'intégration à la base de données via SQL. L'intégration directe préfère VECTOR_EMBEDDING pour les configurations de modèle résidant dans la base de données et revient à DBMS_VECTOR_CHAIN.UTL_TO_EMBEDDING lorsque la configuration de vecteur a besoin de la surface de paramètre de fournisseur JSON.

Créez un intégrateur soutenu par l'exécution SQL d'Oracle AI Database.

Paramètres:
- connexion object : connexion Oracle DB ou objet de type pool avec une méthode cursor() ou acquire() appelable.
- model str : identificateur de modèle. Pour le fournisseur "database" par défaut, il doit s'agir d'un identificateur SQL Oracle non guidé ou d'un identificateur qualifié de schéma pour un modèle d'intégration dans la base de données. Le schéma connecté doit pouvoir résoudre ce nom de modèle en SQL. Pour un fournisseur distant, utilisez le nom de modèle ou l'identificateur de modèle spécifique au fournisseur attendu par ce service.
- input_name str : nom d'entrée de modèle utilisé par VECTOR_EMBEDDING lorsque la configuration du vecteur cible un modèle résidant dans la base de données. La valeur par défaut est "DATA", nom d'entrée utilisé par les métadonnées et les exemples de modèle d'intégration d'Oracle DBMS_VECTOR ONNX. Transmettez le nom d'entrée du modèle réel ici si le modèle importé utilise un autre attribut.
- embedding_dimension int | None : dimension vectorielle d'intégration facultative. Lorsqu'ils sont fournis, les clients soutenus par la base de données peuvent créer ou valider des schémas vectoriels sans envoyer de requête de sonde de dimension. Lorsqu'elle est omise, la dimension est inférée paresseusement avec une demande d'intégration de sonde.
- max_input_tokens int – Budget maximal de jeton d'entrée utilisé par le segment de stockage par défaut. Lorsqu'elle est omise, la propriété max_input_tokens valide une sonde de modèle de base de données dimensionnée en jetons d'entrée 512 estimés et met en cache 512 en tant que restauration conservatrice. Elle n'exécute pas un tokenizer de modèle localement. Par conséquent, définissez max_input_tokens manuellement en fonction du budget d'entrée documenté du modèle.
- normalize bool – Indique si les intégrations L2 doivent être normalisées après leur extraction de la base de données.
- query_prefix str | None : préfixe facultatif ajouté uniquement lors de l'intégration de textes de requête.
- batch_size int – Nombre maximal de textes regroupés dans un aller-retour d'intégration SQL.
- fournisseur str – Fournisseur d'intégration configuré dans Oracle AI Database. La valeur par défaut, "database", utilise un modèle d'intégration chargé dans Oracle Database, généralement au format ONNX. Les fournisseurs distants incluent des services tels que Cohere, OpenAI, Google AI et Oracle Cloud Infrastructure Generative AI. Les services compatibles OpenAI tels que vLLM utilisent "openai" avec l'adresse de service dans provider_options. Reportez-vous à la documentation DBMS_VECTOR_CHAIN d'Oracle pour connaître les fournisseurs pris en charge et leur configuration : https://docs.oracle.com/en/database/oracle/oracle-database/26/vecse/dbms_vector_chain-vecse.html
- provider_options Mapping[str, Any] | None – Paramètres de vecteur Oracle facultatifs, tels que url, credential_name ou host="local". Les arguments de constructeur remplacent provider, model et input_name dans ce mapping. Options du fournisseur de documents Oracle et procédure de création d'informations d'identification de base de données à l'adresse : 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

Exemples

Utilisez un pool de connexions Oracle et un modèle d'intégration résidant sur la base de données :

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

Les noms de modèle qualifiés par schéma peuvent être utilisés lorsque le schéma connecté dispose de privilèges sur un modèle appartenant à un autre schéma :

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

Les exemples suivants montrent comment configurer les intégrations d'Oracle AI Database avec OpenAI, vLLM, Cohere et d'autres fournisseurs :

Exemple OpenAI :

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

Exemple de Cohere :

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

Les services compatibles OpenAI tels que vLLM utilisent également le fournisseur "openai". Définissez host sur "local" lorsque l'adresse ne nécessite pas d'informations d'identification Oracle AI Database :

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

Exemple de Gémeaux :

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

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

Les préfixes propres aux requêtes peuvent être configurés sans modifier l'API de stockage :

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

méthode `embed`

Intégrez un lot de textes en exécutant SQL dans Oracle AI Database.

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 une ligne par texte d'entrée.
Type de retour : numpy.ndarray

Exemples

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

method `embed_async` (async)

Intégrez de manière asynchrone un lot de textes à l'aide d'Oracle AI Database SQL.

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 une ligne par texte d'entrée.
Type de retour : numpy.ndarray

Exemples

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

propriété `embedding_dimension`

Type de retour : int
Description : renvoie la dimension d'intégration configurée ou inférée.
Renvoie : nombre positif de dimensions dans chaque vecteur d'intégration.
Type de retour : int

Notes

Une valeur fournie par le constructeur est renvoyée sans que le modèle de base de données soit contacté. Sinon, la propriété effectue un test une fois et met en cache le résultat pour les accès futurs.

Exemples

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

méthode `get_vectorizer_config_json`

Renvoyer JSON de préférence de vecteur Oracle pour ce modèle de base de données.

La même configuration de modèle est utilisée par l'intégration directe et par les index hybrides gérés. L'intégration directe l'utilise pour déterminer si VECTOR_EMBEDDING peut représenter le modèle de base de données configuré ou si DBMS_VECTOR_CHAIN.UTL_TO_EMBEDDING est nécessaire pour le format JSON du fournisseur. L'indexation hybride le transmet à DBMS_VECTOR_CHAIN.CREATE_PREFERENCE, puis le pipeline de vecteurs d'Oracle détient le travail d'intégration pour cet index.

Retours : charge utile JSON compacte adaptée à DBMS_VECTOR_CHAIN.CREATE_PREFERENCE avec DBMS_VECTOR_CHAIN.VECTORIZER.
Type de retour : str

Exemples

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

propriété `max_input_tokens`

Type de retour : int
Description : renvoie le budget de jeton d'entrée configuré ou inféré pour le découpage par bloc.
Retours : nombre maximum positif de jetons d'entrée pour une charge utile de texte.
Type de retour : int

Notes

Une valeur fournie par le constructeur est renvoyée sans que le modèle de base de données soit contacté. Sinon, la propriété valide une sonde de modèle de base de données dimensionnée en jetons d'entrée 512 estimés et met en cache 512 en tant que restauration conservatrice. Il n'exécute pas un tokenizer de modèle localement. Par conséquent, définissez max_input_tokens manuellement à partir du budget d'entrée documenté du modèle lorsque la précision est importante.

Exemples

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

LLM, embarqueurs et classeurs

Interface LLM

classe oracleagentmemory.apis.llms.ILlm

method generate (résumé)

méthode generate_async (abstrait, asynchrone)

Réponses LLM

classe oracleagentmemory.apis.llms.LlmResponse

texte

Interface Embedder

classe oracleagentmemory.apis.IEmbedder

method embed (résumé)

méthode embed_async (abstrait, asynchrone)

propriété embedding_dimension

propriété max_input_tokens

Interface Reranker

classe oracleagentmemory.apis.IReranker

méthode rerank

méthode rerank_async (abstrait, asynchrone)

classe oracleagentmemory.apis.RerankResponse

classe oracleagentmemory.apis.RerankResponseResult

Adaptateurs LiteLLM

classe oracleagentmemory.core.llms.LlmApiType

CHAT_COMPLETIONS = 'CHAT_COMPLETIONS'

RÉPONSES = 'réponses'

classe oracleagentmemory.core.llms.Llm

méthode generate

method generate_async (async)

propriété supports_vision

classe oracleagentmemory.core.embedders.Embedder

méthode embed

method embed_async (async)

propriété embedding_dimension

propriété max_input_tokens

classe oracleagentmemory.core.Reranker

method rerank_async (async)

Oracle DB Embedders

classe oracleagentmemory.core.embedders.OracleDBEmbedder

méthode embed

method embed_async (async)

propriété embedding_dimension

méthode get_vectorizer_config_json

propriété max_input_tokens

classe `oracleagentmemory.apis.llms.ILlm`

method `generate` (résumé)

méthode `generate_async` (abstrait, asynchrone)

classe `oracleagentmemory.apis.llms.LlmResponse`

classe `oracleagentmemory.apis.IEmbedder`

method `embed` (résumé)

méthode `embed_async` (abstrait, asynchrone)

propriété `embedding_dimension`

propriété `max_input_tokens`

classe `oracleagentmemory.apis.IReranker`

méthode `rerank`

méthode `rerank_async` (abstrait, asynchrone)

classe `oracleagentmemory.apis.RerankResponse`

classe `oracleagentmemory.apis.RerankResponseResult`

classe `oracleagentmemory.core.llms.LlmApiType`

classe `oracleagentmemory.core.llms.Llm`

méthode `generate`

method `generate_async` (async)

propriété `supports_vision`

classe `oracleagentmemory.core.embedders.Embedder`

méthode `embed`

method `embed_async` (async)

propriété `embedding_dimension`

propriété `max_input_tokens`

classe `oracleagentmemory.core.Reranker`

method `rerank_async` (async)

classe `oracleagentmemory.core.embedders.OracleDBEmbedder`

méthode `embed`

method `embed_async` (async)

propriété `embedding_dimension`

méthode `get_vectorizer_config_json`

propriété `max_input_tokens`