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.
- Parâmetros:
- prompt
str | Sequence[dict[str, str]]– Um prompt de texto simples (tratado como uma mensagem de usuário único) ou uma lista de mensagens no estilo de chat, em que cada mensagem é um mapeamento com pelo menos uma chave"content"e, opcionalmente, uma"role". - response_json_schema
dict[str, Any] | None– Esquema JSON Opcional descrevendo o formato de resposta esperado. - **kwargs (Qualquer) – Argumentos de palavra-chave específicos do provedor encaminhados para o backend subjacente.
- prompt
- Devoluções: Saída normalizada do LLM.
- Tipo da devolução: LlmResponse
method generate_async (abstract, async)
Gere de forma assíncrona uma resposta de um LLM.
- Parâmetros:
- prompt
str | Sequence[dict[str, str]]– Um prompt de texto simples (tratado como uma mensagem de usuário único) ou uma lista de mensagens no estilo de chat, em que cada mensagem é um mapeamento com pelo menos uma chave"content"e, opcionalmente, uma"role". - response_json_schema
dict[str, Any] | None– Esquema JSON Opcional descrevendo o formato de resposta esperado. - **kwargs (Qualquer) – Argumentos de palavra-chave específicos do provedor encaminhados para o backend subjacente.
- prompt
- Devoluções: Saída normalizada do LLM.
- Tipo da devolução: LlmResponse
Respostas LLM
classe oracleagentmemory.apis.llms.LlmResponse
Bases: object
Uma pequena resposta normalizada retornada por ILlm.
- Parâmetros: texto
str
text
O conteúdo de texto gerado principal.
- Tipo: str
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.
- Parâmetros:
- textos
list[str]– Batch de textos a serem incorporados. - is_query
bool– Se o lote está sendo incorporado para recuperação de tempo de consulta.
- textos
- Retorna: Um array 2D com formato
(len(texts), dim)comdtype=float32. - Tipo da devolução: numpy.ndarray
method embed_async (abstract, async)
Incorpore um lote de textos em um array NumPy 2D float32.
- Parâmetros:
- textos
list[str]– Batch de textos a serem incorporados. - is_query
bool– Se o lote está sendo incorporado para recuperação de tempo de consulta.
- textos
- Retorna: Um array 2D com formato
(len(texts), dim)comdtype=float32. - Tipo da devolução: numpy.ndarray
propriedade embedding_dimension
- Tipo de Retorno: int
- Descrição: Retorna o tamanho das incorporações produzidas por este incorporador.
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.
- Retorna: Número positivo de valores de ponto flutuante em cada vetor incorporado.
- Tipo de retorno: int
propriedade max_input_tokens
- Tipo de Retorno: int
- Descrição: Retorna o máximo de tokens de entrada suportados.
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.
- Retorna: Contagem máxima positiva de token de entrada para um payload de texto.
- Tipo de retorno: int
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.
- Parâmetros:
- model
str– Identificador de modelo enviado ao provedor de modelo subjacente. - api_base
str | None– URL base opcional para um ponto final compatível com OpenAI. - api_key
str | None– Chave de API opcional usada ao entrar em contato com o provedor. - api_type
LlmApiType– Família de API a ser chamada. UseLlmApiType.CHAT_COMPLETIONSpara Conclusões de Bate-papo ouLlmApiType.RESPONSESpara a API de Respostas. O padrão éLlmApiType.CHAT_COMPLETIONS. - stream
bool– Se deseja solicitar uma saída de streaming. O stream é consumido internamente e retornado como um únicoLlmResponse. - temperature
float | None– Temperatura de amostragem opcional. - max_tokens
int | None– Limite de token de saída opcional. Comapi_type=LlmApiType.CHAT_COMPLETIONS, isso é enviado comomax_tokens. Isso não é suportado pela família de modelos"oci/openai.gpt-5". - reasoning_effort
str | None– Esforço de raciocínio opcional. Comapi_type=LlmApiType.CHAT_COMPLETIONS, isso é enviado comoreasoning_effort. Com oapi_type=LlmApiType.RESPONSES, ele é convertido emreasoning={"effort": ...}. - **default_kwargs (Any) – Argumentos de palavra-chave padrão avançados aplicados a cada chamada. Prefira os parâmetros explícitos acima para configurações comuns de conexão e geração. Quando a mesma definição é fornecida explicitamente e em
default_kwargs, o parâmetro explícito tem precedência.
- model
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.
- Parâmetros:
- prompt
str | Sequence[dict[str, str]]– String de prompt ou mensagens de chat. Uma string é tratada como uma mensagem de usuário único. - response_json_schema
dict[str, Any] | None– Esquema JSON Opcional descrevendo o formato de resposta esperado. Quando fornecido, este método usa o mecanismo de saída estruturada nativo do provedor viaresponse_formatcompatível com OpenAI. - **kwargs (Qualquer) – Parâmetros de chamada adicionais enviados com essa solicitação. Informe
api_type=LlmApiType.RESPONSESpara rotear esta chamada por meio da API de Respostas.
- prompt
- Devoluções: Saída normalizada do LLM.
- Tipo da devolução: LlmResponse
método generate_async (assíncrono)
Gerar uma resposta de forma assíncrona.
- Parâmetros:
- prompt
str | Sequence[dict[str, str]]– String de prompt ou mensagens de chat. Uma string é tratada como uma mensagem de usuário único. - response_json_schema
dict[str, Any] | None– Esquema JSON Opcional descrevendo o formato de resposta esperado. Quando fornecido, este método usa o mecanismo de saída estruturada nativo do provedor viaresponse_formatcompatível com OpenAI. - **kwargs (Qualquer) – Parâmetros de chamada adicionais enviados com essa solicitação. Informe
api_type=LlmApiType.RESPONSESpara rotear esta chamada por meio da API de Respostas.
- prompt
- Devoluções: Saída normalizada do LLM.
- Tipo da devolução: LlmResponse
classe oracleagentmemory.core.embedders.Embedder
Bases: IEmbedder
Embedder apoiado pelo profissional de saúde.
Crie um incorporador apoiado pelo provedor.
- Parâmetros:
- modelo
str– Identificador de modelo enviado ao provedor de incorporação subjacente. - api_base
str | None– URL base opcional para um ponto final compatível com OpenAI. - api_key
str | None– Chave de API opcional usada ao entrar em contato com o provedor. - embedding_dimension
int | None– Dimensão vetorial de incorporação opcional. Quando fornecidos, os clientes com suporte do BD podem criar ou validar esquemas vetoriais sem enviar uma sondagem do provedor. Quando omitido,embedding_dimensioninfere a dimensão preguiçosamente com uma pequena sonda de fallback. - max_input_tokens
int– Contagem máxima de token de entrada suportada pelo modelo de incorporação. Quando omitida, a propriedademax_input_tokensvalida uma sondagem do provedor dimensionada para uma estimativa de tokens de entrada512e armazena em cache512como um fallback conservador. Ele não executa um tokenizador de modelo localmente, portanto, definamax_input_tokensmanualmente com base no orçamento de entrada documentado do modelo. - normalizar
bool– Se as incorporações de normalização L2 serão retornadas pelo provedor. - query_prefix
str | None– Prefixo opcional adicionado somente ao incorporar textos de consulta. - document_prefix
str | None– Prefixo opcional adicionado somente ao incorporar textos sem consulta. - truncate_prompt_tokens
int | None– Limite de token de entrada opcional encaminhado para provedores que oferecem suporte ao truncamento de prompts de incorporação longa. - **default_kwargs (Any) – Argumentos de palavra-chave padrão avançados aplicados a cada chamada de incorporação. Prefira os parâmetros explícitos acima para configurações comuns.
- modelo
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.
- Parâmetros:
- texts
list[str]– Batch de strings de texto bruto a serem incorporadas. - is_query
bool– Se o texto é uma consulta. Os textos de consulta recebemquery_prefixe os textos sem consulta recebemdocument_prefixquando configurados.
- texts
- Retorna: Uma matriz
float32bidimensional com os vetores de incorporação retornados pelo provedor. - Tipo da devolução: numpy.ndarray
- Gera: RuntimeError – Se o payload de resposta do provedor não incluir dados de incorporação.
método embed_async (assíncrono)
Incorporar de forma assíncrona um lote de textos usando o profissional de saúde configurado.
- Parâmetros:
- texts
list[str]– Batch de strings de texto bruto a serem incorporadas. - is_query
bool– Se o texto é uma consulta. Os textos de consulta recebemquery_prefixe os textos sem consulta recebemdocument_prefixquando configurados.
- texts
- Retorna: Uma matriz
float32bidimensional com os vetores de incorporação retornados pelo provedor. - Tipo da devolução: numpy.ndarray
- Gera: RuntimeError – Se o payload de resposta do provedor não incluir dados de incorporação.
propriedade embedding_dimension
- Tipo de Retorno: int
-
Descrição: Retorna a dimensão de incorporação configurada ou inferida.
- Retorna: Número positivo de dimensões em cada vetor de incorporação.
- Tipo de retorno: int
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
- Tipo de Retorno: int
-
Descrição: Retorna o limite de token de entrada de incorporação configurado ou inferido.
- Retorna: Contagem máxima positiva de token de entrada para um payload de texto.
- Tipo de retorno: int
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.
- Parâmetros:
- connection
object– Oracle DB connection or pool-like object with a callablecursor()oracquire()method. - modelo
str– Identificador SQL Oracle sem cotação, ou identificador qualificado por esquema, para o modelo de incorporação no banco de dados. O esquema conectado deve ser capaz de resolver este nome de modelo em SQL. - input_name
str– Nome de entrada do modelo usado porVECTOR_EMBEDDINGquando a configuração do vetorizador é direcionada a um modelo residente do banco de dados. O padrão é"DATA", o nome de entrada usado pelos exemplos e metadados de modelo de incorporação DBMS_VECTOR ONNX da Oracle. Informe o nome de entrada do modelo real aqui se o modelo importado usar um atributo diferente. - embedding_dimension
int | None– Dimensão vetorial de incorporação opcional. Quando fornecidos, os clientes suportados pelo BD podem criar ou validar esquemas vetoriais sem enviar uma consulta de sondagem de dimensão. Quando omitida, a dimensão é inferida preguiçosamente com uma solicitação de incorporação de sonda. - max_input_tokens
int– Orçamento máximo de token de entrada usado pelo chunker de armazenamento padrão. Quando omitida, a propriedademax_input_tokensvalida uma sondagem de modelo de banco de dados dimensionada para um número estimado de tokens de entrada512e armazena em cache512como um fallback conservador. Ele não executa um tokenizador de modelo localmente, portanto, definamax_input_tokensmanualmente com base no orçamento de entrada documentado do modelo. - normalizar
bool– Se serão normalizadas para L2 depois que forem extraídas do banco de dados. - query_prefix
str | None– Prefixo opcional adicionado somente ao incorporar textos de consulta. - batch_size
int– Número máximo de textos agrupados em um único SQL que incorpora ida e volta.
- connection
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.
- Parâmetros:
- texts
list[str]– Batch de strings de texto bruto a serem incorporadas. - is_query
bool– Se o texto é uma consulta. Os textos de consulta recebemquery_prefixquando um foi configurado.
- texts
- Retorna: Uma matriz
float32bidimensional com uma linha por texto de entrada. - Tipo da devolução: numpy.ndarray
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.
- Parâmetros:
- texts
list[str]– Batch de strings de texto bruto a serem incorporadas. - is_query
bool– Se o texto é uma consulta. Os textos de consulta recebemquery_prefixquando um foi configurado.
- texts
- Retorna: Uma matriz
float32bidimensional com uma linha por texto de entrada. - Tipo da devolução: numpy.ndarray
Exemplos de
embedder = OracleDBEmbedder(
connection=pool,
model="DOC_MODEL",
)
matrix = await embedder.embed_async(["hello"])
matrix.shape
(1, 384)
propriedade embedding_dimension
- Tipo de Retorno: int
-
Descrição: Retorna a dimensão de incorporação configurada ou inferida.
- Retorna: Número positivo de dimensões em cada vetor de incorporação.
- Tipo de retorno: int
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.
- Retorna: Payload JSON compacto adequado para
DBMS_VECTOR_CHAIN.CREATE_PREFERENCEcomDBMS_VECTOR_CHAIN.VECTORIZER. - Tipo de retorno: str
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
- Tipo de Retorno: int
-
Descrição: Retorna o orçamento de token de entrada configurado ou inferido para chunking.
- Retorna: Contagem máxima positiva de token de entrada para um payload de texto.
- Tipo de retorno: int
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