LLMs e Incorporadores

Esta página apresenta as interfaces abstratas usadas para conectar LLMs e incorporadores à Memória do Agente Oracle.

Interface LLM

classe oracleagentmemory.apis.llms.ILlm

Bases: ABC

Interface abstrata para chamada de LLM.

method generate (abstract)

Gerar uma resposta de um LLM de forma síncrona.

method generate_async (abstract, async)

Gere de forma assíncrona uma resposta de um LLM.

Respostas LLM

classe oracleagentmemory.apis.llms.LlmResponse

Bases: object

Uma pequena resposta normalizada retornada por ILlm.

text

O conteúdo de texto gerado principal.

Interface do Incorporador

classe oracleagentmemory.apis.IEmbedder

Bases: ABC

Interface de resumo para incorporadores de texto.

method embed (abstract)

Incorpore um lote de textos em um array NumPy 2D float32.

method embed_async (abstract, async)

Incorpore um lote de textos em um array NumPy 2D float32.

propriedade embedding_dimension

As subclasses podem substituir essa propriedade quando a largura de incorporação é conhecida dos metadados da configuração ou do provedor. A implementação padrão verifica embed() uma vez e armazena em cache o tamanho do resultado.

propriedade max_input_tokens

As subclasses podem substituir essa propriedade quando o orçamento de entrada do modelo é conhecido dos metadados de configuração ou provedor. A implementação padrão valida uma sondagem dimensionada para tokens de entrada 512 estimados uma vez e armazena em cache 512 como um fallback conservador. Ele não executa um tokenizador de modelo localmente, portanto, os chamadores devem definir max_input_tokens manualmente quando o orçamento de entrada real do modelo for conhecido.

Adaptadores LiteLLM

classe oracleagentmemory.core.llms.LlmApiType

Bases: str, Enum

Famílias de API compatíveis com OpenAI suportadas para Llm.

CHAT_COMPLETIONS = 'CHAT_COMPLETIONS'

RESPOSTAS = 'respostas'

classe oracleagentmemory.core.llms.Llm

Bases: ILlm

Adaptador para gerar respostas do modelo.

Crie um adaptador LLM.

Exemplos de

Os modelos da OCI Generative AI usam os identificadores de modelo "oci/..." da LiteLLM. Uma configuração comum é passar detalhes de autenticação de chave de API do OCI do arquivo de configuração padrão do OCI por meio de argumentos de palavra-chave específicos do LiteLLM. O OCI Python SDK não é instalado por este pacote; os aplicativos que já dependem dele podem passar alternativamente um objeto 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.")

Os modelos hospedados pelo OpenAI usam identificadores de modelo LiteLLM, como "openai/gpt-5.1" e uma chave de API OpenAI. As Conclusões de Chat são a família de API padrão.

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.")

Use api_type=LlmApiType.RESPONSES quando o modelo de destino tiver que ser chamado por meio da API de Respostas OpenAI em vez de Conclusões de 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'

Servidores compatíveis com OpenAI auto-hospedados, incluindo vLLM, são chamados com um identificador de modelo "openai/..." mais o URL base /v1 do servidor. Informe um api_key nominal, como "none", quando o ponto final não impor a autenticação.

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étodo generate

Gerar uma resposta.

método generate_async (assíncrono)

Gerar uma resposta de forma assíncrona.

classe oracleagentmemory.core.embedders.Embedder

Bases: IEmbedder

Embedder apoiado pelo profissional de saúde.

Crie um incorporador apoiado pelo provedor.

Exemplos de

Os modelos de incorporação da OCI Generative AI usam identificadores de modelo "oci/...". Uma configuração comum é passar detalhes de autenticação de chave de API do OCI do arquivo de configuração padrão do OCI por meio de argumentos de palavra-chave específicos do LiteLLM. O OCI Python SDK não é instalado por este pacote; os aplicativos que já dependem dele podem passar alternativamente um objeto 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"])

Os modelos de incorporação hospedados em OpenAI usam identificadores, como "openai/text-embedding-3-small", com uma chave de 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"])

Servidores de incorporação compatíveis com OpenAI hospedados automaticamente, incluindo vLLM, usam o prefixo do provedor "hosted_vllm/..." com o URL base /v1 do servidor.

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étodo embed

Incorpore um lote de textos usando o provedor configurado.

método embed_async (assíncrono)

Incorporar de forma assíncrona um lote de textos usando o profissional de saúde configurado.

propriedade embedding_dimension

Observações

Um valor fornecido pelo construtor é retornado sem contatar o provedor. Caso contrário, a propriedade sonda uma vez e armazena em cache o resultado.

propriedade max_input_tokens

Observações

Um valor fornecido pelo construtor é retornado sem contatar o provedor. Caso contrário, a propriedade valida uma sondagem do provedor dimensionada para tokens de entrada 512 estimados e armazena em cache 512 como um fallback conservador. Ele não executa um tokenizador de modelo localmente, portanto, defina max_input_tokens manualmente com base no orçamento de entrada documentado do modelo quando a precisão for importante.

Incorporadores do Oracle DB

classe oracleagentmemory.core.embedders.OracleDBEmbedder

Bases: IEmbedder

Incorporar texto chamando o SQL de incorporação do Oracle Database.

Este incorporador mantém o contrato de incorporador existente do pacote intacto enquanto delega a geração de incorporação ao banco de dados por meio do SQL. A incorporação direta prefere VECTOR_EMBEDDING para configurações de modelo residentes no banco de dados e retorna para DBMS_VECTOR_CHAIN.UTL_TO_EMBEDDING quando a configuração do vetorizador precisa da superfície do parâmetro do provedor JSON.

Crie um incorporador baseado na execução do Oracle Database SQL.

Exemplos de

Use um pool de conexões Oracle e um modelo de incorporação residente no BD:

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"])

Os nomes de modelo qualificados para esquema podem ser usados quando o esquema conectado tiver privilégios em um modelo pertencente a outro esquema:

shared_embedder = OracleDBEmbedder(
    connection=pool,
    model="MY_OTHER_SCHEMA.MY_ONNX_MODEL",
    embedding_dimension=768,
)
shared_embedder.embed(["hello world"])

Os prefixos específicos da consulta podem ser configurados sem alterar a API do armazenamento:

embedder = OracleDBEmbedder(
    connection=pool,
    model="DOC_MODEL",
    query_prefix="search_document: ",
)
embedder.embed(["pizza"], is_query=True)

método embed

Incorpore um lote de textos executando SQL no Oracle Database.

Exemplos de

embedder = OracleDBEmbedder(
    connection=pool,
    model="DOC_MODEL",
)
matrix = embedder.embed(["alpha", "beta"])
matrix.shape[0]
2

método embed_async (assíncrono)

Incorporar de forma assíncrona um lote de textos usando o Oracle Database SQL.

Exemplos de

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

propriedade embedding_dimension

Observações

Um valor fornecido pelo construtor é retornado sem entrar em contato com o modelo de banco de dados. Caso contrário, a propriedade sonda uma vez e armazena em cache o resultado para acessos futuros.

Exemplos de

embedder = OracleDBEmbedder(
    connection=pool,
    model="DOC_MODEL",
    embedding_dimension=768,
)
embedder.embedding_dimension
768

método get_vectorizer_config_json

Retorna JSON de preferência do vetorizador Oracle para este modelo de banco de dados.

A mesma configuração de modelo é usada pela incorporação direta e por índices híbridos gerenciados. A incorporação direta a usa para decidir se VECTOR_EMBEDDING pode representar o modelo de banco de dados configurado ou se DBMS_VECTOR_CHAIN.UTL_TO_EMBEDDING é necessário para o provedor JSON. A indexação híbrida passa para DBMS_VECTOR_CHAIN.CREATE_PREFERENCE e, em seguida, o pipeline do vetorizador da Oracle possui trabalho de incorporação para esse índice.

Exemplos de

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

propriedade max_input_tokens

Observações

Um valor fornecido pelo construtor é retornado sem entrar em contato com o modelo de banco de dados. Caso contrário, a propriedade valida uma sondagem de modelo de banco de dados dimensionada para tokens de entrada 512 estimados e armazena em cache 512 como um fallback conservador. Ele não executa um tokenizador de modelo localmente, portanto, defina max_input_tokens manualmente com base no orçamento de entrada documentado do modelo quando a precisão for importante.

Exemplos de

embedder = OracleDBEmbedder(
    connection=pool,
    model="DOC_MODEL",
    max_input_tokens=2048,
)
embedder.max_input_tokens
2048