WeKnora Starter Guide: crea tu primera base de conocimiento RAG
Guía práctica para principiantes que explica cómo desplegar WeKnora con Docker, configurar LLM y Embedding, crear una base de conocimiento y probar RAG.
Indice de contenidos
Si es la primera vez que utilizas WeKnora, la forma más sencilla de entenderlo es como un sistema de base de conocimiento y RAG con IA desarrollado como proyecto de código abierto por Tencent. Puede procesar e indexar documentos como PDF, Word o Markdown y permitir que un modelo de lenguaje responda preguntas basándose en ese contenido.
Su principal diferencia frente a un chatbot convencional es que las respuestas pueden basarse en tu propia base de conocimiento y mostrar referencias al contenido original. WeKnora también incorpora actualmente capacidades como Agent, MCP y Wiki, pero para una primera toma de contacto no necesitas aprenderlo todo de golpe.
Este tutorial tiene un único objetivo:
Iniciar WeKnora → configurar los modelos → crear una base de conocimiento → subir documentos → completar la indexación → realizar tu primera consulta RAG.
¿Qué necesitas preparar antes de empezar?
La guía oficial de inicio rápido con Docker indica actualmente Git, Docker y Docker Compose como requisitos básicos del entorno.
También necesitas al menos un servicio de modelos:
| Tipo | Función |
|---|---|
| LLM | Comprender las preguntas y generar respuestas |
| Embedding | Convertir documentos y preguntas en vectores para realizar búsquedas |
| Rerank | Volver a ordenar los resultados recuperados; es opcional |
| Ollama | Puede utilizarse como servicio de modelos local |
WeKnora es compatible actualmente con Ollama y también con diferentes modelos remotos y APIs compatibles con OpenAI. Los proveedores disponibles pueden variar, por lo que conviene consultar la página de gestión de modelos o la API de la versión que estés utilizando.
Para una primera prueba, lo más sencillo es disponer de una API de modelos en la nube que funcione correctamente o de un entorno local con Ollama ya instalado. No intentes configurar varios modelos al mismo tiempo desde el principio.
Obtener WeKnora
Abre una terminal:
git clone https://github.com/Tencent/WeKnora.git
cd WeKnora
El primer comando descarga el repositorio oficial en tu equipo y el segundo entra en el directorio del proyecto. El despliegue oficial mediante Docker comienza precisamente desde aquí.
A continuación, copia la plantilla de variables de entorno:
cp .env.example .env
.env es uno de los principales puntos de configuración del despliegue. La plantilla oficial incluye actualmente opciones relacionadas con la base de datos, Redis, almacenamiento, bases de datos vectoriales, Neo4j, LLM, Embedding, Rerank, Ollama, autenticación y funciones como Agent y Sandbox.
No necesitas rellenar todas las variables durante la primera instalación. Muchas tienen valores predeterminados o corresponden a funciones opcionales. Empieza siguiendo los comentarios incluidos en el .env.example de la versión que estés utilizando y modifica únicamente lo que necesites.
Iniciar los servicios principales
El método recomendado actualmente por la documentación oficial es:
docker compose pull
docker compose up -d
pull descarga las imágenes correspondientes a la configuración actual y up -d inicia los servicios en segundo plano. La documentación oficial también recomienda ejecutar primero docker compose pull al actualizar de versión para evitar seguir utilizando una imagen antigua almacenada localmente.
Después de iniciar los servicios, puedes comprobar los contenedores con:
docker compose ps
Comprueba especialmente que los servicios principales aparezcan en estado normal. Si algún contenedor se reinicia continuamente, puedes consultar sus registros:
docker compose logs --tail=100
Una vez iniciado correctamente, abre:
http://localhost
para acceder a la interfaz Web de WeKnora. La configuración actual de Compose asigna por defecto el puerto 80 del equipo anfitrión a la interfaz frontend, mientras que la API backend utiliza por defecto el puerto 8080.
Configurar tu primer modelo
WeKnora no es un modelo de lenguaje. Se encarga de gestionar el conocimiento, realizar búsquedas y coordinar aplicaciones de IA, por lo que necesita conectarse a servicios de modelos.
De forma básica, puedes entender los modelos en tres categorías:
LLM: genera la respuesta final.
Embedding: convierte documentos y preguntas en vectores para encontrar contenido semánticamente relevante dentro de la base de conocimiento.
Rerank: vuelve a ordenar los resultados recuperados inicialmente para mejorar la relevancia de los candidatos.
La gestión de modelos de WeKnora permite actualmente utilizar APIs remotas y modelos locales mediante Ollama. Los modelos pueden configurarse por separado para funciones como KnowledgeQA, Embedding y Rerank.
Si utilizas Ollama, el .env.example oficial incluye actualmente por defecto:
OLLAMA_BASE_URL=http://host.docker.internal:11434
Ollama está configurado además como una función opcional, por lo que su indisponibilidad no debería impedir que se inicien los servicios principales.
Primero inicia Ollama en el equipo anfitrión:
ollama serve
Después, añade el modelo correspondiente desde la sección de gestión de modelos de la interfaz Web según la configuración de la versión actual.
Ten en cuenta que WeKnora dentro de Docker y Ollama ejecutándose en el equipo anfitrión no están en el mismo entorno de red. La configuración actual de Compose incorpora host.docker.internal para facilitar esta conexión, aunque puede haber diferencias según el sistema operativo y el entorno de Docker.
Si utilizas una API remota, normalmente tendrás que introducir el nombre del modelo, la URL base de la API, la API Key y el Provider correspondiente. La documentación oficial actual incluye proveedores como OpenAI, Tencent Hunyuan, DeepSeek, Gemini, SiliconFlow, Jina y OpenRouter, entre otros.
Crear tu primera base de conocimiento
Una vez configurados los modelos, puedes entrar en el flujo RAG propiamente dicho.
Crea una base de conocimiento desde la interfaz Web y sube un documento sencillo.
Para la primera prueba, puedes utilizar:
El manual de un producto
Un documento Markdown propio
Documentación interna de la empresa que puedas utilizar
El README de un proyecto
No empieces subiendo cientos de archivos.
Después de la carga, WeKnora procesará los documentos, los dividirá en Chunks y los indexará. La versión actual admite diferentes tipos de materiales, como PDF, Word, PPT, Excel, Markdown, HTML e imágenes, y puede utilizar distintos mecanismos de procesamiento según el tipo de documento.
Espera a que finalice el procesamiento antes de entrar en la interfaz de preguntas y respuestas.
Tu primera consulta RAG
Para la primera prueba, no empieces con preguntas demasiado complejas. Puedes probar consecutivamente tres tipos:
Pregunta factual:
¿De qué trata principalmente este documento?
Pregunta de localización:
¿Qué funciones principales se mencionan en el documento?
Pregunta de síntesis:
Según el contenido del documento, resume las tres características más importantes de este producto.
Este es el flujo RAG básico de WeKnora:
Pregunta del usuario → búsqueda en la base de conocimiento → recuperación del contenido relevante → envío al modelo → generación de la respuesta.
El sistema también permite mostrar referencias en las respuestas, de modo que puedes consultar posteriormente el contenido original correspondiente.
¿Cómo saber si tu primer RAG funciona correctamente?
No te limites a comprobar si la página ha generado una respuesta.
Puedes hacer una prueba muy sencilla.
Primero pregunta algo cuya respuesta aparezca claramente en el documento:
¿Cuál es el precio del producto indicado en el documento?
Después pregunta algo que el documento no mencione en absoluto:
¿Cuándo se lanzará la próxima generación de este producto?
Presta especial atención a la segunda pregunta.
Si la información no existe en la base de conocimiento, ¿el modelo reconoce que no dispone de datos suficientes o se inventa una respuesta?
También debes comprobar si las referencias mostradas realmente respaldan la respuesta.
Si el resultado no es bueno, puedes revisar progresivamente toda la cadena:
procesamiento del documento → Chunk → Embedding → recuperación → Rerank → LLM.
WeKnora ofrece actualmente Chunking configurable, recuperación híbrida mediante vectores y BM25, fusión RRF y Rerank. Por tanto, el resultado del RAG no depende únicamente del modelo de conversación.
Después de probar RAG, experimenta con Agent
Una vez que el RAG básico funcione, puedes empezar a probar el Agent de WeKnora.
El proyecto incluye actualmente un Agent basado en ReAct capaz de coordinar la recuperación de conocimiento, herramientas MCP, Skills, Sandboxes y Web Search para resolver tareas más complejas.
Por ejemplo, el RAG convencional resulta adecuado para:
Resume las funciones del producto según su documentación.
Mientras que un Agent puede utilizarse para:
Basándote en la información del producto disponible en la base de conocimiento y combinándola con resultados de búsquedas externas, prepara un análisis de la competencia.
La principal diferencia es que RAG se centra principalmente en encontrar conocimiento, mientras que un Agent también puede decidir qué debería hacer a continuación.
Aun así, durante el primer despliegue no es necesario iniciar todos los servicios solo para probar el Agent.
No actives todos los componentes opcionales al mismo tiempo
Docker Compose proporciona actualmente varios Profiles.
Por ejemplo, para activar el Knowledge Graph:
docker compose --profile neo4j pull
docker compose --profile neo4j up -d
Para Langfuse:
docker compose --profile langfuse pull
docker compose --profile langfuse up -d
También puedes utilizar el Profile full para activar más funciones de una sola vez. La configuración oficial incluye además componentes opcionales como minio.
Para una primera toma de contacto, conviene seguir una regla sencilla:
primero haz funcionar el RAG básico y después añade componentes.
De lo contrario, cuando aparezca un problema será mucho más difícil determinar si la causa está en el modelo, la recuperación, la base de datos o alguno de los servicios adicionales.
Problemas frecuentes
¿Qué hago si Docker se inicia pero localhost no se abre?
Primero comprueba:
docker compose ps
Después consulta los registros:
docker compose logs --tail=100
Comprueba también que el puerto 80 no esté siendo utilizado por otro programa. La dirección Web predeterminada de la configuración oficial actual es http://localhost.
¿Por qué la base de conocimiento tiene documentos pero las respuestas son malas?
Primero comprueba que el procesamiento de los documentos haya terminado correctamente. Después revisa la configuración de Embedding, recuperación y Rerank.
También debes comprobar que la pregunta realmente pueda responderse a partir de los documentos que has cargado.
¿Puedo utilizar exclusivamente modelos locales?
WeKnora admite actualmente modelos locales mediante Ollama, por lo que puedes configurar LLM, Embedding y otros modelos para utilizar fuentes locales.
Sin embargo, que los modelos puedan ejecutarse localmente no significa que todas las dependencias del despliegue funcionen automáticamente sin conexión. Esto dependerá de los servicios y fuentes de datos que hayas activado en la versión concreta que estés utilizando.
¿docker compose down elimina la base de conocimiento?
No debes confundir los contenedores con los volúmenes de datos.
docker compose down
detiene y elimina los contenedores y redes creados por Compose. En cambio:
docker compose down -v
también elimina los volúmenes de datos asociados.
Durante una primera instalación, no ejecutes down -v sin saber exactamente qué estás eliminando. Los volúmenes pueden contener datos de la base de datos, archivos y otra información persistente.
¿Qué puedes hacer después?
La ruta más recomendable para empezar con WeKnora es bastante sencilla:
Iniciar Docker → configurar LLM/Embedding → crear una base de conocimiento → subir un documento → esperar a que termine la indexación → probar RAG → experimentar después con Agent.
Si simplemente quieres probar un RAG de código abierto, con esto es suficiente para empezar.
Si quieres utilizar WeKnora para construir tu propia plataforma de conocimiento con IA, entonces puedes continuar explorando MCP, Auto-Wiki, Knowledge Graph, Langfuse, REST API, CLI, despliegue privado y Workspace/RBAC.
No intentes aprender todas las funciones desde el primer día.
Primero consigue que tu primer documento responda correctamente a tu primera pregunta. Después podrás ampliar progresivamente WeKnora desde una herramienta que «responde sobre documentos» hasta convertirlo en un auténtico sistema de conocimiento con IA.