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.
• 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.
• 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.
• 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

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. Com api_type=LlmApiType.RESPONSES, isso é enviado como max_output_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": ...}.
  • **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 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 via response_format compatível com OpenAI.
  • **kwargs (Qualquer) – Parâmetros de chamada adicionais enviados com essa solicitação. Informe api_type=LlmApiType.RESPONSES para rotear esta chamada por meio da API de Respostas.
• 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 via response_format compatível com OpenAI.
  • **kwargs (Qualquer) – Parâmetros de chamada adicionais enviados com essa solicitação. Informe api_type=LlmApiType.RESPONSES para rotear esta chamada por meio da API de Respostas.
• 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.
  • 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.
  • 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.

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 recebem query_prefix quando um foi configurado.
• 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 quando um foi configurado.
• 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.