LLM e integraciones

Esta página presenta las interfaces abstractas utilizadas para conectar LLM y embebedores a la memoria del agente de Oracle.

Interfaz de LLM

clase oracleagentmemory.apis.llms.ILlm

Bases: ABC

Interfaz abstracta para la llamada de LLM.

method generate (resumen)

Generar una respuesta de un LLM de forma síncrona.

• Parámetros:
  • prompt str | Sequence[dict[str, str]]: una petición de datos de texto sin formato (tratada como un único mensaje de usuario) o una lista de mensajes de estilo de chat, donde cada mensaje es una asignación con al menos una clave "content" y, opcionalmente, un "role".
  • response_json_schema dict[str, Any] | None: esquema JSON opcional que describe el formato de respuesta esperado.
  • **kwargs (Cualquiera): argumentos de palabra clave específicos del proveedor reenviados al backend subyacente.
• Devoluciones: salida del LLM normalizada.
• Tipos de retorno: LlmResponse

method generate_async (abstract, async)

Generar una respuesta de forma asíncrona desde un LLM.

• Parámetros:
  • prompt str | Sequence[dict[str, str]]: una petición de datos de texto sin formato (tratada como un único mensaje de usuario) o una lista de mensajes de estilo de chat, donde cada mensaje es una asignación con al menos una clave "content" y, opcionalmente, un "role".
  • response_json_schema dict[str, Any] | None: esquema JSON opcional que describe el formato de respuesta esperado.
  • **kwargs (Cualquiera): argumentos de palabra clave específicos del proveedor reenviados al backend subyacente.
• Devoluciones: salida del LLM normalizada.
• Tipo de retorno: LlmResponse

Respuestas de LLM

clase oracleagentmemory.apis.llms.LlmResponse

Bases: object

Una pequeña respuesta normalizada devuelta por ILlm.

• Parámetros: text str

texto

Contenido de texto generado principal.

• Tipo: str

Interfaz de incrustación

clase oracleagentmemory.apis.IEmbedder

Bases: ABC

Interfaz abstracta para incrustadores de texto.

method embed (resumen)

Embeber un lote de textos en una matriz 2D float32 NumPy.

• Parámetros:
  • textos list[str]: lote de textos que se incrustarán.
  • is_query bool: indica si el lote se está embebiendo para la recuperación de tiempo de consulta.
• Devoluciones: matriz 2D con forma de (len(texts), dim) con dtype=float32.
• Tipo de retorno: numpy.ndarray

method embed_async (abstract, async)

Embeber un lote de textos en una matriz 2D float32 NumPy.

• Parámetros:
  • textos list[str]: lote de textos que se incrustarán.
  • is_query bool: indica si el lote se está embebiendo para la recuperación de tiempo de consulta.
• Devoluciones: matriz 2D con forma de (len(texts), dim) con dtype=float32.
• Tipo de retorno: numpy.ndarray

Adaptadores LiteLLM

clase oracleagentmemory.core.llms.LlmApiType

Bases: str, Enum

Familias de API compatibles con OpenAI admitidas para Llm.

CHAT_COMPLETIONS *= 'compleciones_chat'*

RESPUESTAS *= 'respuestas'*

clase oracleagentmemory.core.llms.Llm

Bases: ILlm

Adaptador para generar respuestas de modelo.

Cree un adaptador de LLM.

• Parámetros:
  • model str: identificador de modelo enviado al proveedor de modelos subyacente.
  • api_base str | None: URL base opcional para un punto final compatible con OpenAI.
  • api_key str | None: clave de API opcional que se utiliza al ponerse en contacto con el proveedor.
  • api_type LlmApiType: familia de API a la que llamar. Utilice LlmApiType.CHAT_COMPLETIONS para finalizaciones de chat o LlmApiType.RESPONSES para la API de respuestas. El valor por defecto es LlmApiType.CHAT_COMPLETIONS.
  • stream bool: indica si se debe solicitar una salida de flujo. El flujo se consume internamente y se devuelve como un único LlmResponse.
  • temperatura float | None: temperatura de muestreo opcional.
  • max_tokens int | None: límite de token de salida opcional. Con api_type=LlmApiType.CHAT_COMPLETIONS, se envía como max_tokens. Con api_type=LlmApiType.RESPONSES, se envía como max_output_tokens.
  • reasoning_effort str | None: esfuerzo de razonamiento opcional. Con api_type=LlmApiType.CHAT_COMPLETIONS, se envía como reasoning_effort. Con api_type=LlmApiType.RESPONSES, se convierte en reasoning={"effort": ...}.
  • **default_kwargs (Cualquiera): argumentos avanzados de palabras clave predeterminados aplicados a cada llamada. Preferir los parámetros explícitos anteriores para la configuración común de conexión y generación. Cuando se proporciona el mismo valor de forma explícita y en default_kwargs, el parámetro explícito tiene prioridad.

Ejemplos

Los modelos de OCI Generative AI utilizan los identificadores de modelo "oci/..." de LiteLLM. Una configuración común es transferir los detalles de autenticación de clave de API de OCI del archivo de configuración de OCI estándar a través de argumentos de palabra clave específicos de LiteLLM. El SDK de Python de OCI no está instalado en este paquete; las aplicaciones que ya dependen de él también pueden transferir un 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.")

Los modelos alojados en OpenAI utilizan identificadores de modelo LiteLLM como "openai/gpt-5.1" y una clave de API de OpenAI. Chat Completions es la familia de API por defecto.

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

Utilice api_type=LlmApiType.RESPONSES cuando se deba llamar al modelo de destino a través de la API de respuestas de OpenAI en lugar de las finalizaciones 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'

Los servidores compatibles con OpenAI autoalojados, incluida la vLLM, se llaman con un identificador de modelo "openai/..." más la URL base /v1 del servidor. Transfiera un valor api_key nominal, como "none", cuando el punto final no aplique la autenticación.

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

Generación de una respuesta.

• Parámetros:
  • prompt str | Sequence[dict[str, str]]: cadena de petición de datos o mensajes de chat. Una cadena se trata como un mensaje de usuario único.
  • response_json_schema dict[str, Any] | None: esquema JSON opcional que describe el formato de respuesta esperado. Cuando se proporciona, este método utiliza el mecanismo de salida estructurado nativo del proveedor a través de response_format compatible con OpenAI.
  • **kwargs (cualquiera): parámetros de llamada adicionales enviados con esta solicitud. Transfiera api_type=LlmApiType.RESPONSES para enrutar esta llamada a través de la API de respuestas.
• Devoluciones: salida del LLM normalizada.
• Tipos de retorno: LlmResponse

method generate_async (async)

Generar una respuesta de forma asíncrona.

• Parámetros:
  • prompt str | Sequence[dict[str, str]]: cadena de petición de datos o mensajes de chat. Una cadena se trata como un mensaje de usuario único.
  • response_json_schema dict[str, Any] | None: esquema JSON opcional que describe el formato de respuesta esperado. Cuando se proporciona, este método utiliza el mecanismo de salida estructurado nativo del proveedor a través de response_format compatible con OpenAI.
  • **kwargs (cualquiera): parámetros de llamada adicionales enviados con esta solicitud. Transfiera api_type=LlmApiType.RESPONSES para enrutar esta llamada a través de la API de respuestas.
• Devoluciones: salida del LLM normalizada.
• Tipo de retorno: LlmResponse

clase oracleagentmemory.core.embedders.Embedder

Bases: IEmbedder

Embebido respaldado por el profesional asistencial.

Cree un embebido respaldado por un proveedor.

• Parámetros:
  • model str: identificador de modelo enviado al proveedor de incrustación subyacente.
  • api_base str | None: URL base opcional para un punto final compatible con OpenAI.
  • api_key str | None: clave de API opcional que se utiliza al ponerse en contacto con el proveedor.
  • normalize bool: indica si el proveedor debe normalizar o no las incrustaciones devueltas por el proveedor.
  • query_prefix str | None: prefijo opcional agregado solo al incrustar textos de consulta.
  • truncate_prompt_tokens int | None: límite de token de entrada opcional reenviado a los proveedores que admiten el truncamiento de peticiones de datos de incrustación largas.
  • **default_kwargs (Cualquiera): argumentos de palabra clave predeterminados avanzados aplicados a cada llamada incrustada. Preferir los parámetros explícitos anteriores para la configuración común.

Ejemplos

Los modelos de integración de OCI Generative AI utilizan identificadores de modelo "oci/...". Una configuración común es transferir los detalles de autenticación de clave de API de OCI del archivo de configuración de OCI estándar a través de argumentos de palabra clave específicos de LiteLLM. El SDK de Python de OCI no está instalado en este paquete; las aplicaciones que ya dependen de él también pueden transferir un 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"])

Los modelos de incrustación alojados en OpenAI utilizan identificadores como "openai/text-embedding-3-small" con una clave de API de 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"])

Los servidores embebidos compatibles con OpenAI autoalojados, incluida vLLM, utilizan el prefijo de proveedor "hosted_vllm/..." con la URL base /v1 del 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

Incruste un lote de textos con el profesional asistencial configurado.

• Parámetros:
  • textos list[str]: lote de cadenas de texto sin formato que se incrustarán.
  • is_query bool: indica si el texto es una consulta. Los textos de consulta reciben query_prefix cuando se configura uno.
• Devoluciones: matriz float32 bidimensional con los vectores de incrustación devueltos por el proveedor.
• Tipo de retorno: numpy.ndarray
• Elevaciones: RuntimeError: si la carga útil de respuesta del proveedor no incluye la incrustación de datos.

method embed_async (async)

Embeber de forma asíncrona un lote de textos mediante el proveedor configurado.

• Parámetros:
  • textos list[str]: lote de cadenas de texto sin formato que se incrustarán.
  • is_query bool: indica si el texto es una consulta. Los textos de consulta reciben query_prefix cuando se configura uno.
• Devoluciones: matriz float32 bidimensional con los vectores de incrustación devueltos por el proveedor.
• Tipo de retorno: numpy.ndarray
• Elevaciones: RuntimeError: si la carga útil de respuesta del proveedor no incluye la incrustación de datos.