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 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.
- invite
- 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.
- invite
- 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.
- textes
- Retours : tableau 2D en forme de
(len(texts), dim)avecdtype=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.
- textes
- Retours : tableau 2D en forme de
(len(texts), dim)avecdtype=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
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. UtilisezLlmApiType.CHAT_COMPLETIONSpour les fins de discussion ouLlmApiType.RESPONSESpour l'API des réponses. La valeur par défaut estLlmApiType.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émentLlmResponseunique. - temperature
float | None– Température d'échantillonnage facultative. - max_tokens
int | None: limite de jeton de sortie facultative. Avecapi_type=LlmApiType.CHAT_COMPLETIONS, il est envoyé en tant quemax_tokens. Cette opération n'est pas prise en charge par la famille de modèles"oci/openai.gpt-5". - reasoning_effort
str | None: effort de raisonnement facultatif. Avecapi_type=LlmApiType.CHAT_COMPLETIONS, il est envoyé en tant quereasoning_effort. Avecapi_type=LlmApiType.RESPONSES, elle est convertie enreasoning={"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.
- model
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 viaresponse_formatcompatible avec OpenAI. - **kwargs (N'importe lequel) – Paramètres d'appel supplémentaires envoyés avec cette demande. Transmettez
api_type=LlmApiType.RESPONSESpour acheminer cet appel via l'API des réponses.
- prompt
- 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 viaresponse_formatcompatible avec OpenAI. - **kwargs (N'importe lequel) – Paramètres d'appel supplémentaires envoyés avec cette demande. Transmettez
api_type=LlmApiType.RESPONSESpour acheminer cet appel via l'API des réponses.
- prompt
- 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. - 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_dimensioninfè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_tokensvalide une sonde de fournisseur dimensionnée en jetons d'entrée512estimés et met en cache512en tant que solution de secours conservatrice. Elle n'exécute pas un tokenizer de modèle localement. Par conséquent, définissezmax_input_tokensmanuellement 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. - **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.
- model
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çoiventquery_prefixet les textes non de requête reçoiventdocument_prefixlorsqu'ils sont configurés.
- textes
- Retours : matrice
float32bidimensionnelle 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çoiventquery_prefixet les textes non de requête reçoiventdocument_prefixlorsqu'ils sont configurés.
- textes
- Retours : matrice
float32bidimensionnelle 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
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
- 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
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.
- Paramètres:
- connexion
object: connexion Oracle DB ou objet de type pool avec une méthodecursor()ouacquire()appelable. - model
str: identificateur SQL Oracle non cité, ou identificateur qualifié de schéma, pour le 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. - input_name
str: nom d'entrée de modèle utilisé parVECTOR_EMBEDDINGlorsque 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_tokensvalide une sonde de modèle de base de données dimensionnée en jetons d'entrée512estimés et met en cache512en tant que restauration conservatrice. Elle n'exécute pas un tokenizer de modèle localement. Par conséquent, définissezmax_input_tokensmanuellement 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.
- connexion
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.
- 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çoiventquery_prefixlorsqu'un texte a été configuré.
- textes
- Retours : matrice
float32bidimensionnelle 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 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çoiventquery_prefixlorsqu'un texte a été configuré.
- textes
- Retours : matrice
float32bidimensionnelle 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
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.
- Retours : charge utile JSON compacte adaptée à
DBMS_VECTOR_CHAIN.CREATE_PREFERENCEavecDBMS_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"}'
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
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