LLM ed Embedders
Questa pagina presenta le interfacce astratte utilizzate per collegare LLM e incorporatori nella memoria dell'agente Oracle.
Interfaccia LLM
classe oracleagentmemory.apis.llms.ILlm
Basi: ABC
Interfaccia astratta per il richiamo LLM.
metodo generate (abstract)
Genera una risposta da un LLM in modo sincrono.
- Parametri:
- prompt
str | Sequence[dict[str, str]]: prompt di testo normale (trattato come messaggio utente singolo) o elenco di messaggi in stile chat, in cui ogni messaggio è un mapping con almeno una chiave"content"e, facoltativamente, un"role". - response_json_schema
dict[str, Any] | None: schema JSON facoltativo che descrive il formato di risposta previsto. - **kwargs (Qualsiasi): argomenti di parole chiave specifici del provider inoltrati al backend di base.
- prompt
- Restituzioni: output LLM normalizzato.
- Tipo restituito: LlmResponse
metodo generate_async (abstract, asincrono)
Genera in modo asincrono una risposta da un LLM.
- Parametri:
- prompt
str | Sequence[dict[str, str]]: prompt di testo normale (trattato come messaggio utente singolo) o elenco di messaggi in stile chat, in cui ogni messaggio è un mapping con almeno una chiave"content"e, facoltativamente, un"role". - response_json_schema
dict[str, Any] | None: schema JSON facoltativo che descrive il formato di risposta previsto. - **kwargs (Qualsiasi): argomenti di parole chiave specifici del provider inoltrati al backend di base.
- prompt
- Restituzioni: output LLM normalizzato.
- Tipo restituito: LlmResponse
Risposte LLM
classe oracleagentmemory.apis.llms.LlmResponse
Basi: object
Una piccola risposta normalizzata restituita da ILlm.
- Parametri: testo
str
Testo
Contenuto di testo generato principale.
- Tipo: str
Interfaccia incorporamento
classe oracleagentmemory.apis.IEmbedder
Basi: ABC
Interfaccia astratta per gli incorporatori di testo.
metodo embed (abstract)
Incorpora un batch di testi in un array 2D float32 NumPy.
- Parametri:
- testi
list[str]: batch di testi da incorporare. - is_query
bool: indica se il batch viene incorporato per il recupero in fase di query.
- testi
- Restituzioni: un array 2D a forma di
(len(texts), dim)condtype=float32. - Tipo restituito: numpy.ndarray
metodo embed_async (abstract, asincrono)
Incorpora un batch di testi in un array 2D float32 NumPy.
- Parametri:
- testi
list[str]: batch di testi da incorporare. - is_query
bool: indica se il batch viene incorporato per il recupero in fase di query.
- testi
- Restituzioni: un array 2D a forma di
(len(texts), dim)condtype=float32. - Tipo restituito: numpy.ndarray
proprietà embedding_dimension
- Tipo restituito: int.
- Descrizione: restituisce la dimensione delle integrazioni prodotte da questa incorporazione.
Le sottoclassi possono sostituire questa proprietà quando la larghezza di incorporamento è nota dai metadati di configurazione o provider. L'implementazione predefinita esegue il probe embed() una volta e inserisce nella cache la dimensione del risultato.
- Restituzioni: numero positivo di valori a virgola mobile in ogni vettore di incorporamento.
- Tipo restituito: int.
proprietà max_input_tokens
- Tipo restituito: int.
- Descrizione: restituisce il numero massimo di token di input supportati.
Le sottoclassi possono eseguire l'override di questa proprietà quando il budget di input del modello è noto dai metadati di configurazione o provider. L'implementazione predefinita convalida una volta una dimensione di prova con i token di input 512 stimati e inserisce 512 nella cache come fallback conservativo. Non esegue un tokenizer modello localmente, quindi i chiamanti devono impostare max_input_tokens manualmente quando è noto il budget di input effettivo del modello.
- Restituzioni: numero massimo positivo di token di input per un payload di testo.
- Tipo restituito: int.
Adattatori LiteLLM
classe oracleagentmemory.core.llms.LlmApiType
Basi: str, Enum
Famiglie di API compatibili con OpenAI supportate per Llm.
CHAT_COMPLETIONS = 'CHAT_COMPLETIONS'
RISPOSTE = 'risposte'
classe oracleagentmemory.core.llms.Llm
Basi: ILlm
Adattatore per la generazione delle risposte del modello.
Creare un adattatore LLM.
- Parametri:
- modello
str: identificativo del modello inviato al provider del modello di base. - api_base
str | None: URL di base facoltativo per un endpoint compatibile con OpenAI. - api_key
str | None: chiave API facoltativa utilizzata quando si contatta il provider. - api_type
LlmApiType: famiglia di API da chiamare. UtilizzareLlmApiType.CHAT_COMPLETIONSper completamenti chat oLlmApiType.RESPONSESper l'API Risposte. L'impostazione predefinita èLlmApiType.CHAT_COMPLETIONS. - stream
bool: indica se richiedere l'output di streaming. Il flusso viene utilizzato internamente e restituito come singoloLlmResponse. - temperatura
float | None: temperatura di campionamento opzionale. - max_tokens
int | None– Limite facoltativo di token di output. Conapi_type=LlmApiType.CHAT_COMPLETIONSquesto viene inviato comemax_tokens. Non è supportato dalla famiglia di modelli"oci/openai.gpt-5". - reasoning_effort
str | None: impegno di ragionamento facoltativo. Conapi_type=LlmApiType.CHAT_COMPLETIONSquesto viene inviato comereasoning_effort. Conapi_type=LlmApiType.RESPONSESquesto viene convertito inreasoning={"effort": ...}. - **default_kwargs (Qualsiasi): argomenti predefiniti avanzati della parola chiave applicati a ogni chiamata. Preferire i parametri espliciti sopra per le impostazioni di connessione e generazione comuni. Quando la stessa impostazione viene fornita sia in modo esplicito che in
default_kwargs, il parametro esplicito ha la precedenza.
- modello
Esempi
I modelli di AI generativa OCI utilizzano gli identificativi del modello "oci/..." di LiteLLM. Un'impostazione comune consiste nel passare i dettagli di autenticazione della chiave API OCI dal file di configurazione OCI standard tramite argomenti di parola chiave specifici di LiteLLM. L'SDK Python OCI non è installato da questo pacchetto; le applicazioni che già dipendono da esso possono in alternativa passare un oggetto 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.")
I modelli ospitati con OpenAI utilizzano identificatori di modello LiteLLM come "openai/gpt-5.1" e una chiave API OpenAI. Chat completamenti è la famiglia API predefinita.
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.")
Utilizzare api_type=LlmApiType.RESPONSES quando il modello di destinazione deve essere richiamato tramite l'API Risposte OpenAI anziché Completamenti chat.
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'
I server compatibili con OpenAI self-hosted, tra cui vLLM, vengono chiamati con un identificativo del modello "openai/..." più l'URL di base /v1 del server. Passare un valore nominale api_key, ad esempio "none", quando l'endpoint non applica l'autenticazione.
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.")
metodo generate
Genera una risposta.
- Parametri:
- prompt
str | Sequence[dict[str, str]]: stringa di prompt o messaggi di chat. Una stringa viene considerata come un singolo messaggio utente. - response_json_schema
dict[str, Any] | None: schema JSON facoltativo che descrive il formato di risposta previsto. Se fornito, questo metodo utilizza il meccanismo di output strutturato provider-native tramiteresponse_formatcompatibile con OpenAI. - **kwargs (Qualsiasi): parametri di chiamata aggiuntivi inviati con questa richiesta. Passare
api_type=LlmApiType.RESPONSESper instradare questa chiamata tramite l'API Risposte.
- prompt
- Restituzioni: output LLM normalizzato.
- Tipo restituito: LlmResponse
metodo generate_async (asincrono)
Genera una risposta in modo asincrono.
- Parametri:
- prompt
str | Sequence[dict[str, str]]: stringa di prompt o messaggi di chat. Una stringa viene considerata come un singolo messaggio utente. - response_json_schema
dict[str, Any] | None: schema JSON facoltativo che descrive il formato di risposta previsto. Se fornito, questo metodo utilizza il meccanismo di output strutturato provider-native tramiteresponse_formatcompatibile con OpenAI. - **kwargs (Qualsiasi): parametri di chiamata aggiuntivi inviati con questa richiesta. Passare
api_type=LlmApiType.RESPONSESper instradare questa chiamata tramite l'API Risposte.
- prompt
- Restituzioni: output LLM normalizzato.
- Tipo restituito: LlmResponse
classe oracleagentmemory.core.embedders.Embedder
Basi: IEmbedder
Incorporamento supportato dal provider.
Creare un incorporamento supportato dal provider.
- Parametri:
- modello
str: identificativo del modello inviato al provider di incorporamento di base. - api_base
str | None: URL di base facoltativo per un endpoint compatibile con OpenAI. - api_key
str | None: chiave API facoltativa utilizzata quando si contatta il provider. - embedding_dimension
int | None: dimensione vettoriale di incorporamento facoltativa. Se fornito, i client supportati dal database possono creare o convalidare schemi vettoriali senza inviare una prova del provider. Se omesso,embedding_dimensioninfers la dimensione pigramente con una piccola sonda di fallback. - max_input_tokens
int: conteggio massimo dei token di input supportato dal modello di incorporamento. Se omessa, la proprietàmax_input_tokensconvalida una sonda del provider con una dimensione di token di input512stimata e inserisce512nella cache come fallback conservativo. Non esegue un tokenizer modello localmente, quindi impostaremax_input_tokensmanualmente in base al budget di input documentato del modello. - normalize
bool: indica se normalizzare le incorporamenti restituiti dal provider in L2. - query_prefix
str | None: prefisso facoltativo aggiunto solo durante l'incorporamento dei testi delle query. - document_prefix
str | None: prefisso facoltativo aggiunto solo quando si incorporano testi non di query. - truncate_prompt_tokens
int | None: limite facoltativo del token di input inoltrato ai provider che supportano il troncamento dei prompt di incorporamento lunghi. - **default_kwargs (Qualsiasi): argomenti predefiniti avanzati applicati a ogni chiamata di incorporamento. Preferire i parametri espliciti sopra per le impostazioni comuni.
- modello
Esempi
I modelli di incorporamento dell'AI generativa OCI utilizzano identificativi di modello "oci/...". Un'impostazione comune consiste nel passare i dettagli di autenticazione della chiave API OCI dal file di configurazione OCI standard tramite argomenti di parola chiave specifici di LiteLLM. L'SDK Python OCI non è installato da questo pacchetto; le applicazioni che già dipendono da esso possono in alternativa passare un oggetto 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"])
I modelli di incorporamento ospitati con OpenAI utilizzano identificativi come "openai/text-embedding-3-small" con una chiave 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"])
I server di incorporamento compatibili con OpenAI self-hosted, incluso vLLM, utilizzano il prefisso del provider "hosted_vllm/..." con l'URL di base /v1 del server.
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"])
metodo embed
Incorpora un batch di testi utilizzando il provider configurato.
- Parametri:
- testi
list[str]: batch di stringhe di testo raw da incorporare. - is_query
bool: indica se il testo è una query. I testi delle query ricevonoquery_prefixe i testi non delle query ricevonodocument_prefixquando sono configurati.
- testi
- Restituzioni: una matrice
float32bidimensionale con i vettori di incorporamento restituiti dal provider. - Tipo restituito: numpy.ndarray
- Aumenti: RuntimeError: se il payload di risposta del provider non include l'incorporamento dei dati.
metodo embed_async (asincrono)
Incorpora in modo asincrono un batch di testi utilizzando il provider configurato.
- Parametri:
- testi
list[str]: batch di stringhe di testo raw da incorporare. - is_query
bool: indica se il testo è una query. I testi delle query ricevonoquery_prefixe i testi non delle query ricevonodocument_prefixquando sono configurati.
- testi
- Restituzioni: una matrice
float32bidimensionale con i vettori di incorporamento restituiti dal provider. - Tipo restituito: numpy.ndarray
- Aumenti: RuntimeError: se il payload di risposta del provider non include l'incorporamento dei dati.
proprietà embedding_dimension
- Tipo restituito: int.
-
Descrizione: restituisce la dimensione incorporamento configurata o derivata.
- Restituzioni: numero positivo di dimensioni in ogni vettore di incorporamento.
- Tipo restituito: int.
Note
Viene restituito un valore fornito dal costruttore senza contattare il provider. In caso contrario, la proprietà analizza una volta e memorizza il risultato nella cache.
proprietà max_input_tokens
- Tipo restituito: int.
-
Descrizione: restituisce il limite dei token di input di incorporamento configurato o derivato.
- Restituzioni: numero massimo positivo di token di input per un payload di testo.
- Tipo restituito: int.
Note
Viene restituito un valore fornito dal costruttore senza contattare il provider. In caso contrario, la proprietà convalida una sonda del provider con una dimensione di token di input 512 stimata e inserisce 512 nella cache come fallback conservativo. Non esegue un tokenizer modello localmente, quindi impostare max_input_tokens manualmente dal budget di input documentato del modello quando la precisione è importante.
Incorporatori Oracle DB
classe oracleagentmemory.core.embedders.OracleDBEmbedder
Basi: IEmbedder
Incorporare il testo richiamando Oracle Database incorporando SQL.
Questo programma di incorporamento mantiene intatto il contratto di incorporamento esistente del pacchetto mentre delega la generazione dell'incorporamento al database tramite SQL. L'incorporamento diretto preferisce VECTOR_EMBEDDING per le configurazioni dei modelli residenti nel database e rientra in DBMS_VECTOR_CHAIN.UTL_TO_EMBEDDING quando la configurazione di vectorizer richiede la superficie provider-parameter JSON.
Crea un incorporamento supportato dall'esecuzione di Oracle Database SQL.
- Parametri:
- connessione
object: connessione a Oracle DB o oggetto simile a un pool con un metodocursor()oacquire()richiamabile. - modello
str: identificativo SQL Oracle senza virgolette o identificativo qualificato dallo schema per il modello di incorporamento nel database. Lo schema connesso deve essere in grado di risolvere questo nome del modello in SQL. - input_name
str: nome di input del modello utilizzato daVECTOR_EMBEDDINGquando la configurazione di vectorizer si rivolge a un modello residente nel database. Il valore predefinito è"DATA", il nome di input utilizzato dagli esempi e dai metadati di modello di incorporamento Oracle DBMS_VECTOR ONNX. Passare il nome di input del modello effettivo qui se il modello importato utilizza un attributo diverso. - embedding_dimension
int | None: dimensione vettoriale di incorporamento facoltativa. Se fornito, i client supportati dal database possono creare o convalidare schemi vettoriali senza inviare una query di prova dimensione. Se omessa, la dimensione viene dedotta pigramente con una richiesta di incorporamento della sonda. - max_input_tokens
int: budget input-token massimo utilizzato dal chunker area di memorizzazione predefinito. Se omessa, la proprietàmax_input_tokensconvalida una sonda del modello di database con una dimensione di token di input512stimata e inserisce512nella cache come fallback conservativo. Non esegue un tokenizer modello localmente, quindi impostaremax_input_tokensmanualmente in base al budget di input documentato del modello. - normalize
bool: indica se normalizzare gli incorporamenti L2 dopo che sono stati recuperati dal database. - query_prefix
str | None: prefisso facoltativo aggiunto solo durante l'incorporamento dei testi delle query. - dim_batch
int: numero massimo di testi raggruppati in un'unica istruzione SQL di incorporamento di andata e ritorno.
- connessione
Esempi
Utilizzare un connection pool Oracle e un modello di incorporamento residente in DB:
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"])
I nomi dei modelli qualificati per lo schema possono essere utilizzati quando lo schema connesso dispone di privilegi su un modello di proprietà di un altro schema:
shared_embedder = OracleDBEmbedder(
connection=pool,
model="MY_OTHER_SCHEMA.MY_ONNX_MODEL",
embedding_dimension=768,
)
shared_embedder.embed(["hello world"])
I prefissi specifici delle query possono essere configurati senza modificare l'API dell'area di memorizzazione:
embedder = OracleDBEmbedder(
connection=pool,
model="DOC_MODEL",
query_prefix="search_document: ",
)
embedder.embed(["pizza"], is_query=True)
metodo embed
Incorpora un batch di testi eseguendo SQL in Oracle Database.
- Parametri:
- testi
list[str]: batch di stringhe di testo raw da incorporare. - is_query
bool: indica se il testo è una query. I testi delle query ricevonoquery_prefixquando ne è stato configurato uno.
- testi
- Restituzioni: matrice
float32bidimensionale con una riga per testo di input. - Tipo restituito: numpy.ndarray
Esempi
embedder = OracleDBEmbedder(
connection=pool,
model="DOC_MODEL",
)
matrix = embedder.embed(["alpha", "beta"])
matrix.shape[0]
2
metodo embed_async (asincrono)
Incorpora in modo asincrono un batch di testi utilizzando Oracle Database SQL.
- Parametri:
- testi
list[str]: batch di stringhe di testo raw da incorporare. - is_query
bool: indica se il testo è una query. I testi delle query ricevonoquery_prefixquando ne è stato configurato uno.
- testi
- Restituzioni: matrice
float32bidimensionale con una riga per testo di input. - Tipo restituito: numpy.ndarray
Esempi
embedder = OracleDBEmbedder(
connection=pool,
model="DOC_MODEL",
)
matrix = await embedder.embed_async(["hello"])
matrix.shape
(1, 384)
proprietà embedding_dimension
- Tipo restituito: int.
-
Descrizione: restituisce la dimensione incorporamento configurata o derivata.
- Restituzioni: numero positivo di dimensioni in ogni vettore di incorporamento.
- Tipo restituito: int.
Note
Viene restituito un valore fornito dal costruttore senza contattare il modello di database. In caso contrario, la proprietà analizza una volta e memorizza nella cache il risultato per gli accessi futuri.
Esempi
embedder = OracleDBEmbedder(
connection=pool,
model="DOC_MODEL",
embedding_dimension=768,
)
embedder.embedding_dimension
768
metodo get_vectorizer_config_json
Restituisce il JSON delle preferenze di Oracle vectorizer per questo modello DB.
La stessa configurazione del modello viene utilizzata dall'incorporamento diretto e dagli indici ibridi gestiti. L'incorporamento diretto lo utilizza per decidere se VECTOR_EMBEDDING può rappresentare il modello di database configurato o se è necessario DBMS_VECTOR_CHAIN.UTL_TO_EMBEDDING per JSON del provider. L'indicizzazione ibrida lo passa a DBMS_VECTOR_CHAIN.CREATE_PREFERENCE e quindi la pipeline vectorizer di Oracle è proprietaria del lavoro di incorporamento per tale indice.
- Restituzioni: payload JSON compatto adatto per
DBMS_VECTOR_CHAIN.CREATE_PREFERENCEconDBMS_VECTOR_CHAIN.VECTORIZER. - Tipo restituito: str
Esempi
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"}'
proprietà max_input_tokens
- Tipo restituito: int.
-
Descrizione: restituisce il budget input-token configurato o derivato per il chunk.
- Restituzioni: numero massimo positivo di token di input per un payload di testo.
- Tipo restituito: int.
Note
Viene restituito un valore fornito dal costruttore senza contattare il modello di database. In caso contrario, la proprietà convalida una sonda modello di database con una dimensione pari a 512 token di input stimati e inserisce nella cache 512 come fallback conservativo. Non esegue un tokenizer modello localmente, quindi impostare max_input_tokens manualmente dal budget di input documentato del modello quando la precisione è importante.
Esempi
embedder = OracleDBEmbedder(
connection=pool,
model="DOC_MODEL",
max_input_tokens=2048,
)
embedder.max_input_tokens
2048