Saltearse al contenido
Nappai Documentation

Cassandra

El componente Cassandra permite almacenar y buscar documentos en una base de datos Cassandra (o AstraDB) usando embeddings. Con él puedes crear una tabla de vectores, añadir documentos y luego recuperar los más relevantes según una consulta de texto.

¿Cómo funciona?

El componente se conecta a tu base de datos Cassandra mediante la librería cassio.

  1. Conexión: Se inicializa la conexión usando la credencial que hayas configurado en Nappai (Cassandra DB).
  2. Almacenamiento: Cuando seleccionas la operación Add, el componente convierte los datos que le entregues en documentos con embeddings y los inserta en la tabla especificada.
  3. Búsqueda: Con la operación Search envías una consulta de texto y el componente devuelve los documentos más similares, aplicando filtros y umbrales opcionales.
  4. Retriever: Si necesitas usar el vector store como un retriever en un flujo de LangChain, selecciona esta operación y obtendrás un objeto que puedes pasar a otros componentes.

Operaciones

Este componente ofrece varias operaciones que puedes seleccionar según lo que necesites hacer. Solo puedes usar una operación a la vez:

  • Add: Inserta nuevos documentos en la tabla de vectores.
  • Search: Busca los documentos más relevantes a partir de una consulta de texto.
  • Retriever: Devuelve un objeto retriever que puede ser usado en flujos de LangChain.

Para usar el componente, primero selecciona la operación que necesitas en el campo Operation (Operación).

Entradas

Antes de usar el componente, asegúrate de haber configurado una credencial Cassandra DB en la sección de credenciales de Nappai y seleccionarla en el campo Credential del componente.

Campos de Entrada

Los siguientes campos están disponibles para configurar este componente. Cada campo puede estar visible en diferentes operaciones:

  • Embedding: El modelo de embeddings que se usará para convertir los textos en vectores.

    • Visible en: Add, Search, Retriever

  • Ingest Data: Los documentos que quieres almacenar en la tabla.

    • Visible en: Add

  • Operation: Selecciona la operación que quieres ejecutar.

    • Visible en: Add, Search, Retriever

  • Batch Size: Número opcional de datos a procesar en cada lote.

    • Visible en: Add, Search, Retriever

  • Search Body: Términos de búsqueda de texto que se aplicarán a la consulta.

    • Visible en: Add, Search, Retriever

  • Cluster arguments: Diccionario opcional de argumentos adicionales para el clúster Cassandra.

    • Visible en: Add, Search, Retriever

  • Enable Body Search: Habilita la búsqueda en el cuerpo del documento. Debe activarse antes de crear la tabla.

    • Visible en: Add, Search, Retriever

  • Keyspace: Espacio de nombres (o namespace de AstraDB) donde se almacenará la tabla.

    • Visible en: Add, Search, Retriever

  • Number of Results: Cantidad de resultados que quieres devolver.

    • Visible en: Add, Search, Retriever

  • Search Metadata Filter: Diccionario opcional de filtros que se aplicarán a la búsqueda.

    • Visible en: Add, Search, Retriever

  • Search Query: Consulta de texto que se usará para buscar. Deja vacío para recuperar todos los documentos.

    • Visible en: Search

  • Search Score Threshold: Umbral mínimo de similitud para los resultados (solo cuando se usa “Similarity with score threshold”).

    • Visible en: Add, Search, Retriever

  • Search Type: Tipo de búsqueda que se usará.

    • Visible en: Add, Search, Retriever

  • Setup Mode: Modo de configuración de la tabla (Sync, Async, Off).

    • Visible en: Add, Search, Retriever

  • Table Name: Nombre de la tabla (o colección de AstraDB) donde se guardarán los vectores.

    • Visible en: Add, Search, Retriever

  • TTL Seconds: Tiempo de vida opcional para los textos añadidos.

    • Visible en: Add, Search, Retriever

Salidas

  • Retriever: Objeto Retriever (método: build_base_retriever). Útil para integrarlo con flujos de LangChain.
  • Results: Lista de datos (método: search_documents). Contiene los documentos recuperados.
  • Vector Store: Objeto VectorStore (método: cast_vector_store). Representa la tabla de vectores en Cassandra.

Ejemplo de Uso

1. Añadir documentos (Add)

  1. Selecciona la operación Add.
  2. Conecta tu modelo de embeddings en el campo Embedding.
  3. Arrastra un componente de “Upload File” o “Read Text” y conéctalo al campo Ingest Data.
  4. Configura Table Name, Keyspace y opcionalmente TTL Seconds.
  5. Haz clic en Run.
    El componente creará la tabla (si no existe) y almacenará los documentos con sus vectores.
  1. Selecciona la operación Search.
  2. Conecta el mismo modelo de embeddings en Embedding.
  3. Escribe la consulta en Search Query (por ejemplo, “Resumen de la reunión de ventas”).
  4. Ajusta Number of Results y opcionalmente Search Score Threshold.
  5. Haz clic en Run.
    El componente devolverá los documentos más relevantes en el campo Results.

3. Usar como Retriever

  1. Selecciona la operación Retriever.
  2. Conecta el modelo de embeddings.
  3. Configura Table Name y Keyspace.
  4. Haz clic en Run.
    El resultado será un objeto Retriever que puedes pasar a otros componentes de LangChain para generar respuestas basadas en los documentos almacenados.

Componentes Relacionados

  • OpenAI Embeddings – Genera embeddings que puedes usar con Cassandra.
  • LangChain Retriever – Permite usar el retriever de Cassandra en flujos de LangChain.
  • Data Loader – Carga datos desde archivos o bases de datos para alimentar a Cassandra.

Consejos y Mejores Prácticas

  • Usa credenciales seguras: Configura la credencial Cassandra DB en la sección de credenciales y no incluyas datos sensibles directamente en el flujo.
  • Controla el TTL: Si los documentos son temporales, establece un TTL para que se eliminen automáticamente.
  • Optimiza el Batch Size: Un valor mayor puede acelerar la inserción, pero consume más memoria.
  • Habilita Body Search solo cuando sea necesario: Si no necesitas buscar en el cuerpo del documento, desactívalo para ahorrar recursos.
  • Revisa los filtros: Cuando uses Search Metadata Filter, asegúrate de que los campos existan en los documentos para evitar errores.

Consideraciones de Seguridad

  • Credenciales: La credencial Cassandra DB debe guardarse en el gestor de credenciales de Nappai y no debe exponerse en el flujo.
  • Acceso a la base de datos: Asegúrate de que el usuario de Cassandra tenga permisos mínimos necesarios (solo lectura/escritura en el keyspace y tabla).
  • Datos sensibles: Si los documentos contienen información confidencial, considera cifrar el contenido antes de almacenarlo o usar un keyspace con acceso restringido.