SQLRetrieverTool

SQLRetrieverTool es una herramienta que permite a los usuarios de Nappai consultar bases de datos SQL de forma segura y eficiente. Con ella, puedes crear consultas dinámicas que devuelvan texto que luego será usado por los modelos de IA para responder preguntas o generar contenido basado en tus datos.

¿Cómo funciona?

El componente toma la información de la base de datos, un modelo de embedding y una plantilla de consulta SQL. Cuando se ejecuta, sustituye los marcadores de posición en la plantilla por los valores que le pases, ejecuta la consulta en la base de datos y devuelve los resultados como vectores de embedding. Estos vectores se usan luego por el retriever para encontrar la información más relevante y entregarla al modelo de IA.

No necesita ninguna operación adicional; simplemente configura los campos y deja que el componente haga la conexión y la búsqueda.

Entradas

Database Info: Información de conexión a la base de datos (host, puerto, usuario, contraseña, etc.).
Embedding: Modelo de embedding que convertirá el texto de la consulta en vectores para la búsqueda por similitud.
Metadata Schema: Esquema de metadatos que describe la estructura de los datos que se recuperarán.
SQL Query Template: Plantilla de consulta SQL que debe devolver un campo llamado “text”. Puedes usar {[input]} como marcador de posición para insertar valores dinámicos.
Tool Description: Descripción breve de la herramienta que se usará en el retriever.
Tool Name: Nombre identificador de la herramienta dentro del retriever.

Salidas

Tool: Un objeto BaseTool que encapsula la lógica de consulta y puede ser usado directamente por otros componentes de Nappai.

Ejemplo de Uso

Configura la conexión: En el campo Database Info introduce los datos de tu base de datos PostgreSQL.
Define el embedding: Selecciona el modelo de embedding que prefieras (por ejemplo, text-embedding-ada-002).
Especifica el esquema: Proporciona el esquema de metadatos que describa las tablas y columnas relevantes.
Crea la plantilla:
```
SELECT content AS text
FROM articles
WHERE category = '{[category]}'
LIMIT 5;
```
Aquí {[category]} será reemplazado por el valor que le pases al componente.
Añade descripción y nombre:
- Tool Description: “Consulta de artículos por categoría”
- Tool Name: “ArticleFetcher”
Conecta la salida: Usa la salida Tool en un flujo que requiera recuperar información de la base de datos antes de generar una respuesta.

Componentes Relacionados

LibSQLRetrieverToolBase: Clase base que provee la lógica de conexión y ejecución de consultas.
Retriever: Componente que utiliza el objeto BaseTool para buscar información relevante.
Embedding: Herramienta que convierte texto en vectores de alta dimensión.

Consejos y Mejores Prácticas

Mantén la plantilla simple: La consulta debe devolver solo el campo text; evita columnas adicionales que no se necesiten.
Valida los marcadores: Asegúrate de que los placeholders {[input]} coincidan exactamente con los nombres de los parámetros que pasarás.
Controla los límites: Usa LIMIT en la consulta para evitar devolver demasiados registros y reducir la carga.
Revisa los permisos: La cuenta de la base de datos debe tener solo los privilegios necesarios para la consulta.
Prueba con datos de muestra: Antes de usar en producción, ejecuta la plantilla con valores de prueba para verificar que el resultado sea correcto.

Consideraciones de Seguridad

Credenciales seguras: Almacena la información de conexión en variables de entorno o en el gestor de secretos de Nappai.
Evita inyección SQL: Los marcadores {[input]} deben ser reemplazados por parámetros seguros; no concatenes directamente valores de usuario en la cadena SQL.
Auditoría: Registra las consultas ejecutadas para poder rastrear posibles problemas o accesos indebidos.
Limita el acceso: Solo usuarios autorizados deben poder configurar y ejecutar este componente, especialmente si la base de datos contiene información sensible.