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.
• 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.
• 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.
• Restituzioni: un array 2D a forma di (len(texts), dim) con dtype=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.
• Restituzioni: un array 2D a forma di (len(texts), dim) con dtype=float32.
• Tipo restituito: numpy.ndarray

Adattatori LiteLLM

classe oracleagentmemory.core.llms.LlmApiType

Basi: str, Enum

Famiglie di API compatibili con OpenAI supportate per Llm.

CHAT_COMPLETIONS *= 'chat_completamenti'*

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. Utilizzare LlmApiType.CHAT_COMPLETIONS per completamenti chat o LlmApiType.RESPONSES per 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 singolo LlmResponse.
  • temperatura float | None: temperatura di campionamento opzionale.
  • max_tokens int | None – Limite facoltativo di token di output. Con api_type=LlmApiType.CHAT_COMPLETIONS questo viene inviato come max_tokens. Con api_type=LlmApiType.RESPONSES questo viene inviato come max_output_tokens.
  • reasoning_effort str | None: impegno di ragionamento facoltativo. Con api_type=LlmApiType.CHAT_COMPLETIONS questo viene inviato come reasoning_effort. Con api_type=LlmApiType.RESPONSES questo viene convertito in reasoning={"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.

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 tramite response_format compatibile con OpenAI.
  • **kwargs (Qualsiasi): parametri di chiamata aggiuntivi inviati con questa richiesta. Passare api_type=LlmApiType.RESPONSES per instradare questa chiamata tramite l'API Risposte.
• 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 tramite response_format compatibile con OpenAI.
  • **kwargs (Qualsiasi): parametri di chiamata aggiuntivi inviati con questa richiesta. Passare api_type=LlmApiType.RESPONSES per instradare questa chiamata tramite l'API Risposte.
• 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.
  • 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.
  • truncate_prompt_tokens int | None: limite facoltativo di token di input inoltrato ai provider che supportano il troncamento dei prompt di incorporamento lunghi.
  • **default_kwargs (Qualsiasi): argomenti chiave predefiniti avanzati applicati a ogni chiamata di incorporamento. Preferire i parametri espliciti sopra per le impostazioni comuni.

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 ricevono query_prefix quando ne è stato configurato uno.
• Restituzioni: una matrice float32 bidimensionale 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 ricevono query_prefix quando ne è stato configurato uno.
• Restituzioni: una matrice float32 bidimensionale 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.