LLM, Embedders y Rerankers

En esta página se presentan las interfaces abstractas utilizadas para conectar LLM, incrustadores y reformuladores a la memoria de Oracle Agent.

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[Message | Mapping[str, str | Sequence[Mapping[str, Any]]]] | ChatMessageTypedDictT: cadena, secuencia de diccionario de estilo de chat o secuencia de objetos Message. Las cadenas se convierten en mensajes de usuario; el contenido del mensaje puede incluir partes de texto e imágenes. Las partes de la imagen se validan antes de que se envíen al proveedor.
  • response_json_schema dict[str, Any] | None: esquema JSON opcional que describe el formato de respuesta esperado.
  • **kwargs (cualquiera): opciones de llamada adicionales. La Llm incorporada acepta api_type=LlmApiType.RESPONSES para seleccionar la API de respuestas y image_input_limit_config=ImageInputLimitConfig(...) para sustituir los límites de imagen para esa solicitud. Otros argumentos de palabra clave se reenvían al backend subyacente.
• Devoluciones: salida del LLM normalizada.
• Tipo de retorno: LlmResponse

method generate_async (abstract, async)

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

• Parámetros:
  • prompt str | Sequence[Message | Mapping[str, str | Sequence[Mapping[str, Any]]]] | ChatMessageTypedDictT: cadena, secuencia de diccionario de estilo de chat o secuencia de objetos Message. Las cadenas se convierten en mensajes de usuario; el contenido del mensaje puede incluir partes de texto e imágenes. Las partes de la imagen se validan antes de que se envíen al proveedor.
  • response_json_schema dict[str, Any] | None: esquema JSON opcional que describe el formato de respuesta esperado.
  • **kwargs (cualquiera): opciones de llamada adicionales. La Llm incorporada acepta api_type=LlmApiType.RESPONSES para seleccionar la API de respuestas y image_input_limit_config=ImageInputLimitConfig(...) para sustituir los límites de imagen para esa solicitud. Otros argumentos de palabra clave se reenvían 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

propiedad embedding_dimension

• Tipo de devolución: int
• Descripción: devuelve el tamaño de las incrustaciones producidas por este embebido.

Las subclases pueden sustituir esta propiedad cuando el ancho de embebido se conoce a partir de la configuración o los metadatos del proveedor. La implantación por defecto sondea embed() una vez y almacena en caché el tamaño del resultado.

• Devoluciones: número positivo de valores de coma flotante en cada vector de incrustación.
• Tipo de devolución: int

propiedad max_input_tokens

• Tipo de devolución: int
• Descripción: devuelve el máximo de tokens de entrada admitidos.

Las subclases pueden sustituir esta propiedad cuando el presupuesto de entrada del modelo se conoce a partir de metadatos de configuración o proveedor. La implantación por defecto valida un sondeo con un tamaño estimado de tokens de entrada 512 una vez y almacena en caché 512 como una reserva conservadora. No ejecuta un tokenizador de modelo localmente, por lo que los emisores de llamadas deben definir max_input_tokens manualmente cuando se conozca el presupuesto de entrada real del modelo.

• Devoluciones: recuento máximo positivo de tokens de entrada para una carga útil de texto.
• Tipo de devolución: int

Interfaz Reranker

clase oracleagentmemory.apis.IReranker

Bases: ABC

Interfaz abstracta para la reorganización de documentos síncronos y asíncronos.

Las implantaciones deben devolver un resultado por cada documento de entrada. Cada índice de entrada basado en cero debe aparecer exactamente una vez. relevance_score debe ser finito y las puntuaciones más altas deben indicar una mayor relevancia. Los resultados deben ordenarse desde la puntuación más alta hasta la puntuación más baja.

método rerank

Clasifique los documentos de forma síncrona delegándolos a rerank_async.

• Parámetros:
  • query str: consulta de búsqueda utilizada para comparar los documentos.
  • documentos list[str]: texto del documento candidato en orden de entrada estable. Los índices de resultados hacen referencia a las posiciones de esta lista.
  • **kwargs (Cualquiera): opciones específicas del proveedor.
• Devoluciones: complete la clasificación con exactamente los resultados len(documents). Cada índice de entrada aparece una vez, ordenada de la más relevante a la menos relevante.
• Tipo De Retorno: RerankResponse

method rerank_async (abstract, async)

Clasificar documentos de forma asíncrona por relevancia para una consulta.

• Parámetros:
  • query str: consulta de búsqueda utilizada para comparar los documentos.
  • documentos list[str]: texto del documento candidato en orden de entrada estable. Los índices de resultados hacen referencia a las posiciones de esta lista.
  • **kwargs (Cualquiera): opciones específicas del proveedor.
• Devoluciones: complete la clasificación con exactamente los resultados len(documents). Cada índice de entrada aparece una vez, ordenada de la más relevante a la menos relevante.
• Tipo De Retorno: RerankResponse

clase oracleagentmemory.apis.RerankResponse

Bases: object

Clasificación de documentos completa ordenada por puntuación de relevancia descendente.

• Parámetros: results list[RerankResponseResult]

clase oracleagentmemory.apis.RerankResponseResult

Bases: object

El resultado de un documento.

• Parámetros:
  • index int: posición del documento basada en cero en la lista de entrada.
  • relevance_score float: puntuación de relevancia para el par de documentos de consulta. Los valores más altos significan mayor relevancia.
  • documento str | None: texto del documento cuando el proveedor lo devolvió; de lo contrario, None.

Adaptadores LiteLLM

clase oracleagentmemory.core.llms.LlmApiType

Bases: str, Enum

Familias de API compatibles con OpenAI admitidas para Llm.

CHAT_COMPLETIONS = 'CHAT_COMPLETIONS'

RESPONSES = '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.
  • 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": ...}.
  • enable_structured_output_reminder bool: indica si se debe agregar un esquema de salida estructurada a la petición de datos cuando se solicita una salida estructurada. Si se omite, el valor por defecto sigue la ruta del modelo: está activado para vLLM alojado y modelos no cerrados en la ruta "openai/..." explícita de LiteLLM. Defina esto de forma explícita para los nombres de modelo con hardware dedicado u otros puntos finales personalizados.
  • supports_vision bool: indica si este modelo acepta contenido de imagen en peticiones de datos de generación. Cuando se omite, la compatibilidad se detecta perezosamente: el adaptador comprueba primero los metadatos del modelo y, cuando los metadatos no están disponibles, envía un sondeo de imagen roja fijo. Defina el valor como True o False para omitir la detección.
  • image_input_limit_config ImageInputLimitConfig: límites opcionales de imagen sin formato y de imagen por solicitud. Los campos omitidos utilizan los valores por defecto del SDK. La validación permanece activada para cada solicitud de imagen.
  • max_concurrent_requests int | None: número máximo de solicitudes asíncronas permitidas a través de esta instancia del LLM. Omita el valor para utilizar 16. Transfiera None para desactivar la limitación de simultaneidad. Defina esto explícitamente cuando el punto final necesite un comportamiento diferente.
  • proxy str | None: URL de proxy opcional para solicitudes de proveedor. Cuando se proporciona, este proxy explícito tiene prioridad sobre la configuración de proxy del entorno. Si se omite, la configuración del proxy del entorno se utiliza cuando trust_env está activado.
  • trust_env bool: indica si el proveedor solicita la configuración de proxy y TLS de las variables de entorno. El valor por defecto es True cuando se omite. Defina en False para ignorar esos valores de entorno; se sigue utilizando un proxy explícito.
  • key_file str | None: ruta opcional al archivo de clave privada de cliente en formato PEM. Proporcionarlo junto con cert_file cuando el servidor requiera TLS mutua.
  • cert_file str | None: ruta opcional al archivo de cadena de certificados de cliente en formato PEM. Proporcionarlo junto con key_file cuando el servidor requiera TLS mutua.
  • ca_file str | None: ruta opcional a un certificado o grupo de autoridades de certificación de confianza en formato PEM utilizado para verificar el certificado del servidor. Utilice esta opción para una CA privada o que no sea del sistema.
  • **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[Message | Mapping[str, str | Sequence[Mapping[str, Any]]]] | ChatMessageTypedDictT: cadena, secuencia de diccionario de estilo de chat o secuencia de objetos Message. Las cadenas se convierten en mensajes de usuario; el contenido puede incluir partes de texto e imágenes. Las partes de la imagen se validan antes de que se envíen al proveedor.
  • 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. Transfiera api_type=LlmApiType.RESPONSES para enrutar esta llamada a través de la API de respuestas. Para las peticiones de imágenes, transfiera image_input_limit_config=ImageInputLimitConfig(...) para sustituir los límites de imagen de esta instancia Llm para esta solicitud; los campos omitidos heredan la configuración de la instancia. Se envían otros argumentos de palabra clave con la solicitud del proveedor.
• Devoluciones: salida del LLM normalizada.
• Tipo de retorno: LlmResponse

method generate_async (async)

Generar una respuesta de forma asíncrona.

• Parámetros:
  • prompt str | Sequence[Message | Mapping[str, str | Sequence[Mapping[str, Any]]]] | ChatMessageTypedDictT: una secuencia de mensajes de cadena, petición de datos o estilo de chat. Las cadenas se convierten en mensajes de usuario; el contenido puede incluir partes de texto e imágenes. Las partes de la imagen se validan antes de que se envíen al proveedor.
  • 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. Transfiera api_type=LlmApiType.RESPONSES para enrutar esta llamada a través de la API de respuestas. Para las peticiones de imágenes, transfiera image_input_limit_config=ImageInputLimitConfig(...) para sustituir los límites de imagen de esta instancia Llm para esta solicitud; los campos omitidos heredan la configuración de la instancia. Se envían otros argumentos de palabra clave con la solicitud del proveedor.
• Devoluciones: salida del LLM normalizada.
• Tipo de retorno: LlmResponse

propiedad supports_vision

• Tipo de devolución: bool
• Descripción: devuelva si este LLM admite la entrada de imágenes y la detección es lenta.

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.
  • embedding_dimension int | None: dimensión de vector de incrustación opcional. Cuando se proporciona, los clientes respaldados por base de datos pueden crear o validar esquemas vectoriales sin enviar un sondeo de proveedor. Cuando se omite, embedding_dimension infiere la dimensión perezosamente con un pequeño sondeo de reserva.
  • max_input_tokens int: recuento máximo de tokens de entrada admitido por el modelo de incrustación. Cuando se omite, la propiedad max_input_tokens valida un sondeo de proveedor con un tamaño estimado de tokens de entrada 512 y almacena en caché 512 como una reserva conservadora. No ejecuta un tokenizador de modelo localmente, por lo que debe definir max_input_tokens manualmente según el presupuesto de entrada documentado del modelo.
  • 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.
  • document_prefix str | None: prefijo opcional agregado solo al incrustar textos que no sean 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.
  • proxy str | None: URL de proxy opcional para solicitudes de proveedor. Cuando se proporciona, este proxy explícito tiene prioridad sobre la configuración de proxy del entorno. Si se omite, la configuración del proxy del entorno se utiliza cuando trust_env está activado.
  • trust_env bool: indica si el proveedor solicita la configuración de proxy y TLS de las variables de entorno. El valor por defecto es True cuando se omite. Defina en False para ignorar esos valores de entorno; se sigue utilizando un proxy explícito.
  • key_file str | None: ruta opcional al archivo de clave privada de cliente en formato PEM. Proporcionarlo junto con cert_file cuando el servidor requiera TLS mutua.
  • cert_file str | None: ruta opcional al archivo de cadena de certificados de cliente en formato PEM. Proporcionarlo junto con key_file cuando el servidor requiera TLS mutua.
  • ca_file str | None: ruta opcional a un certificado o grupo de autoridades de certificación de confianza en formato PEM utilizado para verificar el certificado del servidor. Utilice esta opción para una CA privada o que no sea del sistema.
  • **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 incrustació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 y los textos que no son de consulta reciben document_prefix cuando están configurados.
• 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 y los textos que no son de consulta reciben document_prefix cuando están configurados.
• 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.

propiedad embedding_dimension

• Tipo de devolución: int

• Descripción: devuelve la dimensión de embebido configurada o inferida.

• Devoluciones: número positivo de dimensiones en cada vector de incrustación.
• Tipo de devolución: int

Notas

Se devuelve un valor proporcionado por el constructor sin ponerse en contacto con el proveedor. De lo contrario, la propiedad sondea una vez y almacena en caché el resultado.

propiedad max_input_tokens

• Tipo de devolución: int

• Descripción: devuelve el límite de token de entrada de embebido configurado o inferido.

• Devoluciones: recuento máximo positivo de tokens de entrada para una carga útil de texto.
• Tipo de devolución: int

Notas

Se devuelve un valor proporcionado por el constructor sin ponerse en contacto con el proveedor. De lo contrario, la propiedad valida un sondeo de proveedor con un tamaño estimado de tokens de entrada 512 y almacena en caché 512 como una reserva conservadora. No ejecuta un tokenizador de modelo localmente, por lo que debe definir max_input_tokens manualmente desde el presupuesto de entrada documentado del modelo cuando sea importante la precisión.

clase oracleagentmemory.core.Reranker

Bases: IReranker

Reranker respaldado por una interfaz de rerank neutral para el proveedor.

• Parámetros:
  • model str: identificador de modelo de Reranker. Prefijo los modelos de OCI Generative AI con oci/, por ejemplo oci/cohere.rerank-v4.0-fast.
  • api_base str | None: URL base opcional para un punto final de cambio compatible con OpenAI.
  • api_key str | None: clave de API opcional que utiliza el proveedor.

  • **default_kwargs (cualquiera):

    Las opciones específicas del profesional asistencial se aplican a cada solicitud de cambio.

    Nota: El cambio de versión de OCI requiere oci_compartment_id, oci_region, oci_user, oci_fingerprint, oci_tenancy y oci_key_file. Instale el grupo de dependencias rerank-oci opcional antes de utilizar un modelo de OCI.

Ejemplos

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

Cree un reranker respaldado por el proveedor.

method rerank_async (async)

Clasificar documentos de forma asíncrona por relevancia para una consulta.

• Parámetros:
  • query str: consulta de búsqueda utilizada para comparar los documentos.
  • documentos list[str]: texto del documento candidato en orden de entrada estable.
  • **kwargs (Cualquiera): opciones específicas del proveedor que se reenvían al proveedor sustituto.
• Devoluciones: clasificación completa de los proveedores ordenada desde la puntuación de relevancia más alta hasta la más baja.
• Tipo De Retorno: RerankResponse

Embebedores de Oracle DB

clase oracleagentmemory.core.embedders.OracleDBEmbedder

Bases: IEmbedder

Embeber texto llamando a Oracle AI Database embebiendo SQL.

Este embebido mantiene intacto el contrato de embebido existente del paquete al delegar la generación de embebido en la base de datos a través de SQL. La incrustación directa prefiere VECTOR_EMBEDDING para las configuraciones de modelo que residen en la base de datos y vuelve a DBMS_VECTOR_CHAIN.UTL_TO_EMBEDDING cuando la configuración del vectorizador necesita la superficie del parámetro del proveedor JSON.

Cree un embebido respaldado por la ejecución de Oracle AI Database SQL.

• Parámetros:
  • connection object: conexión de Oracle DB u objeto similar a un pool con un método cursor() o acquire() que se puede llamar.
  • model str: identificador de modelo. Para el proveedor "database" por defecto, debe ser un identificador SQL de Oracle sin comillas o un identificador cualificado de esquema para un modelo de embebido en la base de datos. El esquema conectado debe poder resolver este nombre de modelo en SQL. Para un proveedor remoto, utilice el nombre de modelo o el identificador de modelo específico del proveedor que espera ese servicio.
  • input_name str: nombre de entrada de modelo que utiliza VECTOR_EMBEDDING cuando la configuración del vectorizador tiene como destino un modelo que reside en la base de datos. El valor por defecto es "DATA", el nombre de entrada utilizado por los ejemplos y metadatos de modelo de embebido DBMS_VECTOR ONNX de Oracle. Transfiera el nombre de entrada del modelo real aquí si el modelo importado utiliza un atributo diferente.
  • embedding_dimension int | None: dimensión de vector de incrustación opcional. Cuando se proporcionan, los clientes respaldados por base de datos pueden crear o validar esquemas vectoriales sin enviar una consulta de sondeo de dimensión. Cuando se omite, la dimensión se infiere perezosamente con una solicitud de embebido de sondeo.
  • max_input_tokens int: presupuesto máximo de token de entrada utilizado por el fragmentador de tienda predeterminado. Cuando se omite, la propiedad max_input_tokens valida un sondeo de modelo de base de datos con un tamaño estimado de tokens de entrada 512 y almacena en caché 512 como una reserva conservadora. No ejecuta un tokenizador de modelo localmente, por lo que debe definir max_input_tokens manualmente según el presupuesto de entrada documentado del modelo.
  • normalizar bool: si se normalizan las incrustaciones de L2 después de que se recuperen de la base de datos.
  • query_prefix str | None: prefijo opcional agregado solo al incrustar textos de consulta.
  • batch_size int: número máximo de textos agrupados en un viaje de ida y vuelta incrustado de SQL.
  • provider str: proveedor de embebido configurado en Oracle AI Database. El valor por defecto, "database", utiliza un modelo de embebido cargado en Oracle Database, normalmente en formato ONNX. Los proveedores remotos incluyen servicios como Cohere, OpenAI, Google AI y Oracle Cloud Infrastructure Generative AI. Los servicios compatibles con OpenAI, como vLLM, utilizan "openai" junto con el punto final de servicio en provider_options. Consulte la documentación de DBMS_VECTOR_CHAIN de Oracle para conocer los proveedores soportados y su configuración: https://docs.oracle.com/en/database/oracle/oracle-database/26/vecse/dbms_vector_chain-vecse.html
  • provider_options Mapping[str, Any] | None: configuración opcional del vectorizador de Oracle, como url, credential_name o host="local". Los argumentos del constructor sustituyen a provider, model y input_name en esta asignación. Opciones del proveedor de documentos de Oracle y cómo crear una credencial de base de datos en: 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

Ejemplos

Utilice un pool de conexiones de Oracle y un modelo de embebido que reside en la base de datos:

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

Los nombres de modelo cualificados para el esquema se pueden utilizar cuando el esquema conectado tiene privilegios en un modelo propiedad de otro esquema:

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

Los siguientes ejemplos muestran cómo configurar incrustaciones de Oracle AI Database con OpenAI, vLLM, Cohere y otros proveedores:

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

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

Los servicios compatibles con OpenAI, como vLLM, también utilizan el proveedor "openai". Defina host en "local" cuando el punto final no necesite una credencial de 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"])

Ejemplo de Géminis:

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

Ejemplo de Hugging Face:

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

Los prefijos específicos de la consulta se pueden configurar sin cambiar la API del almacén:

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

método embed

Integre un lote de textos ejecutando SQL en Oracle AI Database.

• 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 una fila por texto de entrada.
• Tipo de retorno: numpy.ndarray

Ejemplos

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

method embed_async (async)

Embeber de forma asíncrona un lote de textos con Oracle AI Database SQL.

• 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 una fila por texto de entrada.
• Tipo de retorno: numpy.ndarray

Ejemplos

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

propiedad embedding_dimension

• Tipo de devolución: int

• Descripción: devuelve la dimensión de embebido configurada o inferida.

• Devoluciones: número positivo de dimensiones en cada vector de incrustación.
• Tipo de devolución: int

Notas

Se devuelve un valor proporcionado por el constructor sin ponerse en contacto con el modelo de base de datos. De lo contrario, la propiedad sondea una vez y almacena en caché el resultado para accesos futuros.

Ejemplos

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

método get_vectorizer_config_json

Devuelve JSON de preferencia del vectorizador de Oracle para este modelo de base de datos.

La misma configuración de modelo se utiliza mediante incrustación directa y mediante índices híbridos gestionados. La incrustación directa la utiliza para decidir si VECTOR_EMBEDDING puede representar el modelo de base de datos configurado o si DBMS_VECTOR_CHAIN.UTL_TO_EMBEDDING es necesario para el JSON del proveedor. La indexación híbrida la transfiere a DBMS_VECTOR_CHAIN.CREATE_PREFERENCE y, a continuación, el pipeline del vectorizador de Oracle posee el trabajo de embebido para ese índice.

• Devoluciones: carga útil de JSON compacta adecuada para DBMS_VECTOR_CHAIN.CREATE_PREFERENCE con DBMS_VECTOR_CHAIN.VECTORIZER.
• Tipo de devolución: str

Ejemplos

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

propiedad max_input_tokens

• Tipo de devolución: int

• Descripción: devuelve el presupuesto de token de entrada configurado o inferido para la fragmentación.

• Devoluciones: recuento máximo positivo de tokens de entrada para una carga útil de texto.
• Tipo de devolución: int

Notas

Se devuelve un valor proporcionado por el constructor sin ponerse en contacto con el modelo de base de datos. De lo contrario, la propiedad valida un sondeo de modelo de base de datos con un tamaño estimado de tokens de entrada 512 y almacena en caché 512 como una reserva conservadora. No ejecuta un tokenizador de modelo localmente, por lo que debe definir max_input_tokens manualmente desde el presupuesto de entrada documentado del modelo cuando sea importante la precisión.

Ejemplos

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