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.
- prompt
- 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[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.
- prompt
- 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.
- textos
- Devoluciones: matriz 2D con forma de
(len(texts), dim)condtype=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.
- textos
- Devoluciones: matriz 2D con forma de
(len(texts), dim)condtype=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
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. UtiliceLlmApiType.CHAT_COMPLETIONSpara finalizaciones de chat oLlmApiType.RESPONSESpara la API de respuestas. El valor por defecto esLlmApiType.CHAT_COMPLETIONS. - stream
bool: indica si se debe solicitar una salida de flujo. El flujo se consume internamente y se devuelve como un únicoLlmResponse. - temperatura
float | None: temperatura de muestreo opcional. - max_tokens
int | None: límite de token de salida opcional. Conapi_type=LlmApiType.CHAT_COMPLETIONS, se envía comomax_tokens. Esto no está soportado por la familia de modelos"oci/openai.gpt-5". - reasoning_effort
str | None: esfuerzo de razonamiento opcional. Conapi_type=LlmApiType.CHAT_COMPLETIONS, se envía comoreasoning_effort. Conapi_type=LlmApiType.RESPONSES, se convierte enreasoning={"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.
- model
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 deresponse_formatcompatible con OpenAI. - **kwargs (cualquiera): parámetros de llamada adicionales enviados con esta solicitud. Transfiera
api_type=LlmApiType.RESPONSESpara enrutar esta llamada a través de la API de respuestas.
- prompt
- 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[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 deresponse_formatcompatible con OpenAI. - **kwargs (cualquiera): parámetros de llamada adicionales enviados con esta solicitud. Transfiera
api_type=LlmApiType.RESPONSESpara enrutar esta llamada a través de la API de respuestas.
- prompt
- 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. - 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_dimensioninfiere 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 propiedadmax_input_tokensvalida un sondeo de proveedor con un tamaño estimado de tokens de entrada512y almacena en caché512como una reserva conservadora. No ejecuta un tokenizador de modelo localmente, por lo que debe definirmax_input_tokensmanualmente 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. - **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.
- model
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 recibenquery_prefixy los textos que no son de consulta recibendocument_prefixcuando están configurados.
- textos
- Devoluciones: matriz
float32bidimensional 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 recibenquery_prefixy los textos que no son de consulta recibendocument_prefixcuando están configurados.
- textos
- Devoluciones: matriz
float32bidimensional 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.
Embebedores de Oracle DB
clase oracleagentmemory.core.embedders.OracleDBEmbedder
Bases: IEmbedder
Embeber texto llamando a Oracle 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 SQL de Oracle Database.
- Parámetros:
- connection
object: conexión de Oracle DB u objeto similar a un pool con un métodocursor()oacquire()que se puede llamar. - model
str: identificador SQL de Oracle sin comillas o identificador cualificado para el esquema para el modelo de embebido en la base de datos. El esquema conectado debe poder resolver este nombre de modelo en SQL. - input_name
str: nombre de entrada de modelo que utilizaVECTOR_EMBEDDINGcuando 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 propiedadmax_input_tokensvalida un sondeo de modelo de base de datos con un tamaño estimado de tokens de entrada512y almacena en caché512como una reserva conservadora. No ejecuta un tokenizador de modelo localmente, por lo que debe definirmax_input_tokensmanualmente 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.
- connection
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 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
Embeber un lote de textos ejecutando SQL en Oracle 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 recibenquery_prefixcuando se configura uno.
- textos
- Devoluciones: matriz
float32bidimensional 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 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 recibenquery_prefixcuando se configura uno.
- textos
- Devoluciones: matriz
float32bidimensional 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_PREFERENCEconDBMS_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"}'
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