LLMs, Embedders e Rerankers

Esta página apresenta as interfaces abstratas usadas para conectar LLMs, incorporadores e rerankers à 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[Message | Mapping[str, str | Sequence[Mapping[str, Any]]]] | ChatMessageTypedDictT – Uma string, sequência de dicionário de estilo de chat ou sequência de objetos Message. As strings se tornam mensagens do usuário; o conteúdo da mensagem pode incluir partes de texto e imagem. As partes da imagem são validadas antes de serem enviadas ao profissional de saúde.
  • response_json_schema dict[str, Any] | None – Esquema JSON Opcional descrevendo o formato de resposta esperado.
  • **kwargs (Qualquer) – Opções de chamada adicionais. O Llm incorporado aceita api_type=LlmApiType.RESPONSES para selecionar a API de Respostas e image_input_limit_config=ImageInputLimitConfig(...) para substituir os limites de imagem dessa solicitação. Outros argumentos de palavra-chave são encaminhados para o backend subjacente.
• 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[Message | Mapping[str, str | Sequence[Mapping[str, Any]]]] | ChatMessageTypedDictT – Uma string, sequência de dicionário de estilo de chat ou sequência de objetos Message. As strings se tornam mensagens do usuário; o conteúdo da mensagem pode incluir partes de texto e imagem. As partes da imagem são validadas antes de serem enviadas ao profissional de saúde.
  • response_json_schema dict[str, Any] | None – Esquema JSON Opcional descrevendo o formato de resposta esperado.
  • **kwargs (Qualquer) – Opções de chamada adicionais. O Llm incorporado aceita api_type=LlmApiType.RESPONSES para selecionar a API de Respostas e image_input_limit_config=ImageInputLimitConfig(...) para substituir os limites de imagem dessa solicitação. Outros argumentos de palavra-chave são encaminhados para o backend subjacente.
• 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

texto

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.
• Retorna: Um array 2D com formato (len(texts), dim) com dtype=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.
• Retorna: Um array 2D com formato (len(texts), dim) com dtype=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

Interface do Reranker

classe oracleagentmemory.apis.IReranker

Bases: ABC

Interface abstrata para reclassificação de documentos síncronos e assíncronos.

As implementações devem retornar um resultado para cada documento de entrada. Cada índice de entrada baseado em zero deve aparecer exatamente uma vez. relevance_score deve ser finito e pontuações mais altas devem indicar maior relevância. Os resultados devem ser ordenados da pontuação mais alta para a pontuação mais baixa.

método rerank

Classifique documentos de forma síncrona delegando para rerank_async.

• Parâmetros:
  • query str – Consulta de pesquisa usada para comparar os documentos.
  • documentos list[str] – Texto do documento do candidato em ordem de entrada estável. Os índices de resultado se referem às posições nesta lista.
  • **kwargs (Qualquer) – Opções específicas do provedor.
• Retorna: Classificação completa com exatamente len(documents) resultados. Cada índice de entrada aparece uma vez, ordenado do mais relevante para o menos relevante.
• Tipo da devolução: RerankResponse

method rerank_async (abstract, async)

Classifique os documentos de forma assíncrona por relevância para uma consulta.

• Parâmetros:
  • query str – Consulta de pesquisa usada para comparar os documentos.
  • documentos list[str] – Texto do documento do candidato em ordem de entrada estável. Os índices de resultado se referem às posições nesta lista.
  • **kwargs (Qualquer) – Opções específicas do provedor.
• Retorna: Classificação completa com exatamente len(documents) resultados. Cada índice de entrada aparece uma vez, ordenado do mais relevante para o menos relevante.
• Tipo da devolução: RerankResponse

classe oracleagentmemory.apis.RerankResponse

Bases: object

Classificação completa do documento ordenada pela pontuação de relevância decrescente.

• Parâmetros: resultados list[RerankResponseResult]

classe oracleagentmemory.apis.RerankResponseResult

Bases: object

O resultado da nova classificação de um documento.

• Parâmetros:
  • index int – Posição baseada em zero do documento na lista de entrada.
  • relevance_score float – Pontuação de relevância para o par consulta-documento. Valores mais altos significam maior relevância.
  • documento str | None – O texto do documento quando o provedor o retornou, caso contrário, None.

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. Use LlmApiType.CHAT_COMPLETIONS para Conclusões de Bate-papo ou LlmApiType.RESPONSES para 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 único LlmResponse.
  • temperature float | None – Temperatura de amostragem opcional.
  • max_tokens int | None – Limite de token de saída opcional. Com api_type=LlmApiType.CHAT_COMPLETIONS, isso é enviado como max_tokens.
  • reasoning_effort str | None – Esforço de raciocínio opcional. Com api_type=LlmApiType.CHAT_COMPLETIONS, isso é enviado como reasoning_effort. Com o api_type=LlmApiType.RESPONSES, ele é convertido em reasoning={"effort": ...}.
  • enable_structured_output_reminder bool – Se anexar um esquema de saída estruturada ao prompt quando a saída estruturada for solicitada. Se omitido, o padrão seguirá a rota do modelo: ele é ativado para modelos vLLM hospedados e não fechados na rota "openai/..." explícita do LiteLLM. Defina isso explicitamente para nomes de modelo bare ou outros pontos finais personalizados.
  • supports_vision bool – Se este modelo aceita conteúdo de imagem em prompts de geração. Quando omitido, o suporte é detectado preguiçosamente: o adaptador primeiro verifica os metadados do modelo e, quando os metadados estão indisponíveis, envia uma sonda fixa de imagem vermelha. Defina True ou False para ignorar a detecção.
  • image_input_limit_config ImageInputLimitConfig – Limites de imagem raw-image e por-request opcionais. Os campos omitidos usam padrões SDK. A validação permanece ativada para cada solicitação de imagem.
  • max_concurrent_requests int | None – O número máximo de solicitações assíncronas permitidas por meio desta instância do LLM. Omita o valor para usar 16. Informe None para desativar a limitação de simultaneidade. Defina isso explicitamente quando o ponto final precisar de comportamento diferente.
  • proxy str | None – URL de proxy opcional para solicitações de provedor. Quando fornecido, esse proxy explícito tem precedência sobre as definições de proxy do ambiente. Se omitidas, as configurações de proxy do ambiente são utilizadas quando trust_env está ativado.
  • trust_env bool – Se o provedor solicita configurações de proxy de leitura e TLS das variáveis de ambiente. O padrão é True quando omitido. Defina como False para ignorar essas definições de ambiente; ainda é usada uma proxy explícita.
  • key_file str | None – Caminho opcional para o arquivo de chave privada de cliente no formato PEM. Forneça-o junto com cert_file quando o servidor exigir TLS mútuo.
  • cert_file str | None – Caminho opcional para o arquivo de cadeia de certificados cliente no formato PEM. Forneça-o junto com key_file quando o servidor exigir TLS mútuo.
  • ca_file str | None – Caminho opcional para um certificado de CA ou bundle de confiança no formato PEM usado para verificar o certificado do servidor. Use-o para uma CA privada ou não do sistema.
  • **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.

Exemplos

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[Message | Mapping[str, str | Sequence[Mapping[str, Any]]]] | ChatMessageTypedDictT – Uma string, sequência de dicionário de estilo de chat ou sequência de objetos de Mensagem. As strings se tornam mensagens do usuário; o conteúdo pode incluir partes de texto e imagem. As partes da imagem são validadas antes de serem enviadas ao profissional de saúde.
  • 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 via response_format compatível com OpenAI.
  • **kwargs (Qualquer) – Parâmetros de chamada adicionais. Informe api_type=LlmApiType.RESPONSES para rotear esta chamada por meio da API de Respostas. Para prompts de imagem, passe image_input_limit_config=ImageInputLimitConfig(...) para substituir os limites de imagem desta instância do Llm para esta solicitação; os campos omitidos herdam a configuração da instância. Outros argumentos de palavra-chave são enviados com a solicitação do provedor.
• 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[Message | Mapping[str, str | Sequence[Mapping[str, Any]]]] | ChatMessageTypedDictT – Uma sequência de mensagens de string, Prompt ou estilo de chat. As strings se tornam mensagens do usuário; o conteúdo pode incluir partes de texto e imagem. As partes da imagem são validadas antes de serem enviadas ao profissional de saúde.
  • 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 via response_format compatível com OpenAI.
  • **kwargs (Qualquer) – Parâmetros de chamada adicionais. Informe api_type=LlmApiType.RESPONSES para rotear esta chamada por meio da API de Respostas. Para prompts de imagem, passe image_input_limit_config=ImageInputLimitConfig(...) para substituir os limites de imagem desta instância do Llm para esta solicitação; os campos omitidos herdam a configuração da instância. Outros argumentos de palavra-chave são enviados com a solicitação do provedor.
• Devoluções: Saída normalizada do LLM.
• Tipo da devolução: LlmResponse

propriedade supports_vision

• Tipo de Retorno: bool
• Descrição: Retorne se esse LLM suporta entrada de imagem, detectando preguiçosamente.

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_dimension infere 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 propriedade max_input_tokens valida uma sondagem do provedor dimensionada para uma estimativa de tokens de entrada 512 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.
  • 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.
  • proxy str | None – URL de proxy opcional para solicitações de provedor. Quando fornecido, esse proxy explícito tem precedência sobre as definições de proxy do ambiente. Se omitidas, as configurações de proxy do ambiente são utilizadas quando trust_env está ativado.
  • trust_env bool – Se o provedor solicita configurações de proxy de leitura e TLS das variáveis de ambiente. O padrão é True quando omitido. Defina como False para ignorar essas definições de ambiente; ainda é usada uma proxy explícita.
  • key_file str | None – Caminho opcional para o arquivo de chave privada de cliente no formato PEM. Forneça-o junto com cert_file quando o servidor exigir TLS mútuo.
  • cert_file str | None – Caminho opcional para o arquivo de cadeia de certificados cliente no formato PEM. Forneça-o junto com key_file quando o servidor exigir TLS mútuo.
  • ca_file str | None – Caminho opcional para um certificado de CA ou bundle de confiança no formato PEM usado para verificar o certificado do servidor. Use-o para uma CA privada ou não do sistema.
  • **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.

Exemplos

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 recebem query_prefix e os textos sem consulta recebem document_prefix quando configurados.
• Retorna: Uma matriz float32 bidimensional 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 recebem query_prefix e os textos sem consulta recebem document_prefix quando configurados.
• Retorna: Uma matriz float32 bidimensional 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.

classe oracleagentmemory.core.Reranker

Bases: IReranker

Reranker apoiado por uma interface de rerank neutra do provedor.

• Parâmetros:
  • model str – Identificador do modelo Reranker. Prefixe os modelos do OCI Generative AI com oci/, por exemplo, oci/cohere.rerank-v4.0-fast.
  • api_base str | None – URL base opcional para um ponto final de reclassificação compatível com OpenAI.
  • api_key str | None – Chave de API opcional usada pelo provedor.

  • **default_kwargs (Qualquer) –

    Opções específicas do profissional de saúde aplicadas a cada solicitação de nova classificação.

    Observação: A reavaliação do OCI requer oci_compartment_id, oci_region, oci_user, oci_fingerprint, oci_tenancy e oci_key_file. Instale o grupo de dependências rerank-oci opcional antes de usar um modelo do OCI.

Exemplos

reranker = Reranker(
    model="your-reranker-model",
    api_base="https://your-reranker-endpoint/v1",
    api_key="your-api-key",
)
reranker.rerank("favorite food", ["The user likes pasta."])

oci_reranker = Reranker(
    model="oci/cohere.rerank-v4.0-fast",
    oci_compartment_id="ocid1.compartment...",
    oci_region="your-region",
    oci_user="ocid1.user...",
    oci_fingerprint="aa:bb:cc",
    oci_tenancy="ocid1.tenancy...",
    oci_key_file="~/.oci/oci_api_key.pem",
)
oci_reranker.rerank("favorite food", ["The user likes pasta."])

Crie uma nova identificação com suporte do profissional de saúde.

método rerank_async (assíncrono)

Classifique os documentos de forma assíncrona por relevância para uma consulta.

• Parâmetros:
  • query str – Consulta de pesquisa usada para comparar os documentos.
  • documentos list[str] – Texto do documento do candidato em ordem de entrada estável.
  • **kwargs (Qualquer) – Opções específicas do provedor encaminhadas para o provedor de reclassificação.
• Devoluções: Classificação completa do provedor ordenada da pontuação de relevância mais alta para a mais baixa.
• Tipo da devolução: RerankResponse

Incorporadores do Oracle DB

classe oracleagentmemory.core.embedders.OracleDBEmbedder

Bases: IEmbedder

Incorpore texto chamando o Oracle AI Database incorporando SQL.

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 apoiado pela execução do Oracle AI Database SQL.

• Parâmetros:
  • connection object – Oracle DB connection or pool-like object with a callable cursor() or acquire() method.
  • model str – Identificador do modelo. Para o provedor "database" padrão, ele deve ser um identificador SQL Oracle sem aspas ou um identificador qualificado por esquema para um modelo de incorporação no banco de dados. O esquema conectado deve ser capaz de resolver este nome de modelo em SQL. Para um provedor remoto, use o nome do modelo ou o identificador do modelo específico do provedor esperado por esse serviço.
  • input_name str – Nome de entrada do modelo usado por VECTOR_EMBEDDING quando 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 propriedade max_input_tokens valida uma sondagem de modelo de banco de dados dimensionada para um número estimado de tokens de entrada 512 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.
  • 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.
  • fornecedor str – Provedor de incorporação configurado no Oracle AI Database. O padrão, "database", usa um modelo de incorporação carregado no Oracle Database, geralmente no formato ONNX. Os provedores remotos incluem serviços como Cohere, OpenAI, Google AI e Oracle Cloud Infrastructure Generative AI. Serviços compatíveis com OpenAI, como vLLM, usam "openai" junto com o ponto final de serviço em provider_options. Consulte a documentação DBMS_VECTOR_CHAIN da Oracle para obter os provedores suportados e sua configuração: https://docs.oracle.com/en/database/oracle/oracle-database/26/vecse/dbms_vector_chain-vecse.html
  • provider_options Mapping[str, Any] | None – Configurações opcionais do vetorizador Oracle, como url, credential_name ou host="local". Os argumentos do construtor substituem provider, model e input_name neste mapeamento. A Oracle documenta as opções do provedor e como criar uma credencial de banco de dados em: https://docs.oracle.com/en/database/oracle/oracle-database/26/vecse/utl_to_embedding-and-utl_to_embeddings-dbms_vector_chain.html https://docs.oracle.com/en/database/oracle/oracle-database/26/vecse/create_credential-dbms_vector_chain.html

Exemplos

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 exemplos a seguir mostram como configurar incorporações do Oracle AI Database com OpenAI, vLLM, Cohere e outros provedores:

Exemplo OpenAI:

openai_embedder = OracleDBEmbedder(
    connection=pool,
    provider="openai",
    model="text-embedding-3-small",
    provider_options={
        "credential_name": "OPENAI_CRED",
        "url": "https://api.openai.example.com/embeddings",
    },
)
openai_embedder.embed(["hello world"])

Exemplo do Cohere:

cohere_embedder = OracleDBEmbedder(
    connection=pool,
    provider="cohere",
    model="embed-english-v3.0",
    provider_options={
        "credential_name": "COHERE_CRED",
        "url": "https://api.cohere.example.com/embed",
        "input_type": "search_document",
    },
)
cohere_embedder.embed(["hello world"])

Serviços compatíveis com OpenAI, como vLLM, também usam o provedor "openai". Defina host como "local" quando o ponto final não exigir uma credencial do Oracle AI Database:

vllm_embedder = OracleDBEmbedder(
    connection=pool,
    provider="openai",
    model="BAAI/bge-small-en-v1.5",
    provider_options={
        "url": "http://localhost:8080/v1/embeddings",
        "host": "local",
    },
)
vllm_embedder.embed(["hello world"])

Exemplo de Gemini:

gemini_embedder = OracleDBEmbedder(
    connection=pool,
    provider="googleai",
    model="gemini-embedding-001",
    provider_options={
        "credential_name": "GOOGLEAI_CRED",
        "url": "https://googleapis.example.com/models/",
    },
)
gemini_embedder.embed(["hello world"])

Exemplo de rosto abraçado:

huggingface_embedder = OracleDBEmbedder(
    connection=pool,
    provider="huggingface",
    model=(
        "sentence-transformers/all-MiniLM-L6-v2"
    ),
    provider_options={
        "credential_name": "HF_CRED",
        "url": "https://router.huggingface.example.com/",
    },
)
huggingface_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 AI 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 recebem query_prefix quando um foi configurado.
• Retorna: Uma matriz float32 bidimensional com uma linha por texto de entrada.
• Tipo da devolução: numpy.ndarray

Exemplos

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

método embed_async (assíncrono)

Incorpore de forma assíncrona um lote de textos usando o Oracle AI 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 recebem query_prefix quando um foi configurado.
• Retorna: Uma matriz float32 bidimensional com uma linha por texto de entrada.
• Tipo da devolução: numpy.ndarray

Exemplos

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

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_PREFERENCE com DBMS_VECTOR_CHAIN.VECTORIZER.
• Tipo de retorno: str

Exemplos

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"}'
remote_embedder = OracleDBEmbedder(
    connection=pool,
    provider="openai",
    model="text-embedding-3-small",
    provider_options={"host": "local", "url": "http://localhost:8080/v1/embeddings"},
)
remote_embedder.get_vectorizer_config_json()
'{"embedder_spec":{"host":"local","url":"http://localhost:8080/v1/embeddings","provider":"openai","model":"text-embedding-3-small"}}'

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

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