Chat con documentos
El chat con documentos permite que Libre WebUI busque en los documentos subidos y añada fragmentos relevantes al contexto del chat.
Archivos compatibles
Formatos que se pueden subir actualmente:
- PDF (con procedencia por página)
- Texto sin formato y registros
- Markdown (
.md,.markdown,.mdx, con procedencia por sección) - HTML
- Documentos de Word (
.docx) - Presentaciones (
.pptx, con procedencia por diapositiva) - Hojas de cálculo (
.xlsx, con procedencia por hoja) y CSV/TSV - Código fuente (TypeScript, Python, Go, Rust, SQL, YAML y otros lenguajes habituales)
- Imágenes (
.png,.jpg,.webp,.gif): el modelo de visión configurado lee el texto (Ajustes → Valores predeterminados → Modelo de visión) - Audio (
.wav,.webm): se transcribe mediante el proveedor de conversión de voz a texto, tras el mismo control de acceso STT que la entrada de voz - Tamaño máximo del archivo: 10 MB
Los formatos de Office se desempaquetan con un analizador acotado incluido en el repositorio; ninguna biblioteca de documentos de terceros se ejecuta en el proceso del servidor. Si vuelves a subir los mismos bytes al mismo ámbito, se eliminan los duplicados en vez de ingerirlos dos veces.
La extracción de imágenes y audio se dirige a los proveedores que ya has configurado. No se incluye ningún motor local de OCR o reconocimiento de voz, y nada abandona la instancia salvo la llamada al modelo elegido. Un PDF sin capa de texto (un escaneo) se trata igual: se recuperan las imágenes JPEG de sus páginas y el modelo de visión las lee con procedencia por página. Los escaneos guardados en otros formatos de imagen (fax CCITT, JBIG2) siguen sin producir texto. Si no se ha configurado un modelo de visión o un proveedor STT, la subida se marca como fallida y el motivo aparece en Ajustes → Documentos.
El backend procesa los archivos y los almacena con el resto de datos de la aplicación.
Modos de búsqueda
Libre WebUI admite dos modos de recuperación:
| Modo | Cuándo se usa | Notas |
|---|---|---|
| Búsqueda por palabras | Siempre disponible | Clasificación BM25; no requiere un modelo de embeddings |
| Búsqueda híbrida | Embeddings activados en Ajustes | Combina la clasificación vectorial con BM25 mediante fusión recíproca de rangos |
Con los embeddings activados, cada consulta ejecuta ambas clasificaciones y las fusiona: una coincidencia exacta puede superar a un fragmento semánticamente parecido pero más impreciso, y los fragmentos cuyos embeddings aún se generan siguen accesibles por la parte léxica. Si los embeddings fallan o se desactivan, la búsqueda documental vuelve a la coincidencia pura de palabras.
La puntuación léxica se calcula dentro del proceso sobre los fragmentos a los que puedes acceder. Libre no mantiene deliberadamente un índice de texto completo en disco para ellos, porque el texto se almacena cifrado y un índice de tokens conservaría texto sin cifrar junto al cifrado. Un fragmento solo entra en la clasificación léxica si contiene por completo al menos una palabra de la consulta. Por ello, un identificador compuesto como ALPHA_BETA_GAMMA nunca muestra texto que solo comparta uno de sus fragmentos.
Las colecciones de conocimiento compartidas contigo se incorporan automáticamente a ambas clasificaciones. El control de acceso se aplica dentro de la propia consulta vectorial: los permisos se publican en la ACL del índice. Revocar un recurso compartido oculta esos documentos en la siguiente búsqueda sin volver a generar embeddings.
Activar la búsqueda semántica
Instala un modelo de embeddings:
ollama pull nomic-embed-text
Después, abre Ajustes y activa los embeddings. Puedes utilizar modelos de embeddings locales de Ollama o plugins de proveedores compatibles.
Ajustes predeterminados:
- Modelo:
nomic-embed-text - Tamaño del fragmento: 1000 caracteres
- Solapamiento: 200 caracteres
- Umbral de similitud: 0.3
Citas y modo de documento completo
Los fragmentos recuperados incluyen su procedencia: nombre del archivo, índice del fragmento, puntuación de recuperación y, para formatos con mapa de segmentos, la página, diapositiva, hoja o sección de Markdown de origen. El contexto del chat etiqueta cada fragmento con esa ubicación, y el panel Fuentes de la conversación enumera las ubicaciones citadas bajo cada documento.
Cada chat también puede cambiar al modo de documento completo desde el panel Fuentes. En vez de fragmentos recuperados, se envía con el mensaje todo el contenido extraído de cada documento incluido. Un límite de tokens (FULL_DOCUMENT_CONTEXT_MAX_TOKENS, 32000 de forma predeterminada) protege la ventana de contexto: si los documentos lo superan, el chat vuelve a la recuperación y el panel Fuentes explica el motivo.
Subir y buscar
- Sube un archivo compatible desde los controles de documentos.
- Espera a que termine el procesamiento.
- Haz una pregunta en el chat.
- Libre WebUI recupera los fragmentos relevantes de la sesión y los incluye como contexto.
Ejemplos de prompts:
Summarize the uploaded document in five bullets.
What deadlines are mentioned in the PDF?
Find the section that talks about pricing.
Compare the uploaded policy with this proposed change.
Endpoints de la API
| Endpoint | Finalidad |
|---|---|
POST /api/documents/upload | Subir un documento compatible |
GET /api/documents | Enumerar los documentos subidos |
GET /api/documents/session/:sessionId | Enumerar los documentos de una sesión |
POST /api/documents/search | Buscar en los documentos |
DELETE /api/documents/:documentId | Eliminar un documento |
GET /api/documents/embeddings/status | Consultar el estado de los embeddings |
POST /api/documents/embeddings/regenerate | Regenerar los embeddings |
Prácticas recomendadas
- Limita las subidas a la tarea actual.
- Da preferencia a los PDF con texto; los PDF escaneados funcionan mediante el modelo de visión, pero cuestan una llamada por página.
- Regenera los embeddings después de cambiar su modelo.
- Reduce el umbral de similitud si la búsqueda semántica omite contexto útil.
- Aumenta el umbral si los resultados parecen ruidosos.