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.

méthode generate_async (abstrait, asynchrone)

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

Réponses LLM

classe oracleagentmemory.apis.llms.LlmResponse

Bases : object

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

Texte

Contenu de texte généré principal.

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.

méthode embed_async (abstrait, asynchrone)

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

propriété embedding_dimension

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.

propriété max_input_tokens

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.

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.

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.

method generate_async (async)

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

classe oracleagentmemory.core.embedders.Embedder

Bases : IEmbedder

Intégration soutenue par le fournisseur.

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

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é.

method embed_async (async)

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

propriété embedding_dimension

Remarques

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

Remarques

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.

Oracle DB Embedders

classe oracleagentmemory.core.embedders.OracleDBEmbedder

Bases : IEmbedder

Intégrez du texte en appelant le code SQL d'intégration Oracle 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 Database.

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 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 Database.

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 Database SQL.

Exemples 

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

propriété embedding_dimension

Remarques

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.

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

propriété max_input_tokens

Remarques

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