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.

metodo generate_async (abstract, asincrono)

Genera in modo asincrono una risposta da un LLM.

Risposte LLM

classe oracleagentmemory.apis.llms.LlmResponse

Basi: object

Una piccola risposta normalizzata restituita da ILlm.

Testo

Contenuto di testo generato principale.

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.

metodo embed_async (abstract, asincrono)

Incorpora un batch di testi in un array 2D float32 NumPy.

proprietà embedding_dimension

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.

proprietà max_input_tokens

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.

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.

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.

metodo generate_async (asincrono)

Genera una risposta in modo asincrono.

classe oracleagentmemory.core.embedders.Embedder

Basi: IEmbedder

Incorporamento supportato dal provider.

Creare un incorporamento supportato dal provider.

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.

metodo embed_async (asincrono)

Incorpora in modo asincrono un batch di testi utilizzando il provider configurato.

proprietà embedding_dimension

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

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.

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.

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.

Esempi

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

proprietà embedding_dimension

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.

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

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