En este tutorial vamos a ver cómo usar Meilisearch como memoria de un chatbot con IA en Laravel. Partiremos del asistente que creamos para Radios, el taller de bicicletas de ejemplo, y cambiaremos el lugar donde guarda lo que sabe de la web: en vez de un archivo dentro de storage/, un servidor de Meilisearch que combina la búsqueda por palabras con la búsqueda por significado.
Contenidos
Si todavía no lo has hecho, empieza por el tutorial en el que vimos cómo crear un chatbot con IA para tu web con Laravel. Allí construimos la web, el asistente y el panel, y aquí no volveré a explicarlos.
Introducción
Larachat, el paquete con el que montamos el chat, divide cada página en fragmentos y calcula para cada uno un vector que representa su significado. Cuando alguien pregunta, busca los fragmentos más cercanos a la pregunta y se los pasa al modelo. En el primer tutorial esos fragmentos vivían en un archivo PHP, que funciona muy bien hasta unos pocos miles de fragmentos y no necesita ningún servidor.
Meilisearch compensa en otros casos:
- Webs grandes: con decenas de miles de fragmentos, recorrer un archivo en cada pregunta deja de ser razonable.
- Varias webs: un mismo servidor de Meilisearch puede guardar el conocimiento de varias aplicaciones, cada una en sus propios índices.
- Un buscador que ya existe: si tu aplicación ya usa Meilisearch para otras búsquedas, el chat aprovecha el mismo servidor.
Yo lo uso así en kenodo.com: su chat guarda los fragmentos en un Meilisearch que comparte con otras aplicaciones, cada una con una clave que solo le da acceso a sus índices.
Para seguir este tutorial necesitas el proyecto del primero, una clave de OpenAI y Docker, con el que arrancaremos Meilisearch. Si no has usado Docker antes, te vendrá bien leer el tutorial de introducción a Docker. Puedes consultar el código de la aplicación en GitHub. Así se ve el índice de Radios en el panel de Meilisearch al buscar la palabra sábados, con el fragmento de la página de contacto y todos sus campos:

Puesta en marcha de Meilisearch
Lo primero es tener un servidor de Meilisearch en local y conectar Laravel con él.
Arranca Meilisearch con Docker
En lugar de instalar Meilisearch en el sistema, lo arrancaremos en un contenedor. Crea un archivo compose.yaml en la raíz del proyecto:
services:
meilisearch:
image: getmeili/meilisearch:v1.42
environment:
MEILI_MASTER_KEY: ${MEILISEARCH_KEY}
MEILI_ENV: development
MEILI_NO_ANALYTICS: "true"
ports:
- "${MEILISEARCH_PORT:-7700}:7700"
volumes:
- meilisearch:/meili_data
volumes:
meilisearch:
Docker Compose lee las variables del archivo .env del proyecto, así que la clave maestra de Meilisearch será la misma que usará Laravel para conectarse. El volumen conserva los índices aunque borres el contenedor. Añade estas tres variables al .env:
MEILISEARCH_HOST=http://localhost:7700
MEILISEARCH_KEY=
MEILISEARCH_PREFIX=radios_
Para la clave, genera una cadena aleatoria y pégala en MEILISEARCH_KEY. Escríbela solo en el .env, que Laravel ya excluye de git, y nunca en el código ni en .env.example:
openssl rand -hex 16
Ahora arranca el contenedor y comprueba que responde:
docker compose up -d
curl http://localhost:7700/health
La respuesta debe ser {"status":"available"}. Con MEILI_ENV en development, Meilisearch muestra además en http://localhost:7700 un pequeño panel desde el que puedes buscar en los índices, que es el de la captura anterior.
Conecta Laravel con Meilisearch
Larachat no habla con Meilisearch directamente: lo hace a través de Larameili, un paquete que permite trabajar con los índices de Meilisearch como si fueran modelos. Instálalo y publica su configuración:
composer require edulazaro/larameili
php artisan vendor:publish --tag=larameili-config
El archivo config/larameili.php lee las tres variables que hemos añadido. La que más conviene entender es el prefijo: Larameili lo añade al nombre de cada índice, así que el índice chunks de Larachat se llamará radios_chunks en Meilisearch. Gracias al prefijo, varias aplicaciones pueden compartir el mismo servidor sin pisarse los índices.
Cambia el almacén de Larachat
Para que Larachat guarde los fragmentos en Meilisearch basta con cambiar una línea de config/larachat.php. Dentro de knowledge, cambia el valor de driver:
'knowledge' => [
'driver' => 'meilisearch',
// ...
'meilisearch' => [
'index' => 'chunks',
],
// ...
'retrieved_chunks' => 8,
'semantic_ratio' => 0.6,
],
index es el nombre del índice, al que Larameili añadirá el prefijo. retrieved_chunks es el número de fragmentos que recibe el modelo con cada pregunta y semantic_ratio decide cuánto pesa el significado frente a las palabras en la búsqueda. Volveremos a él más adelante.
La base de conocimiento en Meilisearch
Con Meilisearch conectado, vamos a llenar el índice y a ver cómo busca Larachat en él.
Indexa la web
El comando para indexar es el mismo que con el archivo:
php artisan larachat:index
La diferencia está en lo que ocurre antes de guardar nada. Larachat crea el índice radios_chunks si no existe y le aplica su configuración:
- Campos de búsqueda: el título de la página, el encabezado de la sección y el texto del fragmento.
- Campos de filtro: el idioma, la dirección de la página y la fecha de publicación, para no responder con páginas de otro idioma ni con artículos programados.
- Un embedder
userProvided: Meilisearch guarda los vectores que le enviamos, de 512 dimensiones, en lugar de calcularlos él.
Esto último es importante. Meilisearch puede conectarse a OpenAI por su cuenta para calcular los vectores, pero entonces tendría que guardar tu clave de OpenAI. Con userProvided, los vectores los calcula Laravel y llegan ya hechos dentro de cada documento, así que tu clave de OpenAI nunca sale de la aplicación.
Cada fragmento se guarda como un documento con su dirección, su título, su encabezado, su texto, su idioma y un resumen que permite saber si ha cambiado. Al volver a indexar, Larachat compara esos resúmenes y solo vuelve a calcular los vectores de los fragmentos modificados.
Así busca Larachat en Meilisearch
Cuando un visitante pregunta, Larachat calcula el vector de la pregunta y envía a Meilisearch una búsqueda híbrida: el texto de la pregunta y su vector a la vez. Meilisearch ordena los fragmentos combinando dos señales:
- Las palabras: si la pregunta dice "sábados" y un fragmento contiene "Sábados, de 10:00 a 14:00", ese fragmento sube.
- El significado: si alguien pregunta "¿abrís el finde?", ninguna palabra coincide con la página de contacto, pero su vector se parece al del horario.
La búsqueda filtra además por el idioma de la conversación y descarta lo que todavía no se ha publicado. Aparte, Larachat pide los primeros fragmentos de la página que está viendo el visitante, para que una pregunta como "¿y esto cuánto cuesta?" tenga contexto.
Ajusta el peso del significado
semantic_ratio va de 0 a 1. Con 0, Meilisearch solo tiene en cuenta las palabras. Con 1, solo los vectores. El valor por defecto, 0.6, da algo más de peso al significado, que es lo que conviene en un chat: la gente pregunta con sus propias palabras, no con las de tu web.
Si tu web está llena de nombres propios, referencias o códigos que los visitantes escriben tal cual, como modelos de bicicleta o números de pieza, bajar el valor a 0.4 o 0.5 hará que esas coincidencias exactas pesen más. Si notas que el chat no encuentra respuestas cuando los visitantes usan sinónimos, súbelo.
Meilisearch en producción
En producción hay tres cosas que cambian respecto al contenedor de desarrollo:
- El modo: con
MEILI_ENV=production, Meilisearch desactiva su panel web y exige una clave maestra de al menos 16 bytes. - La clave de la aplicación: no uses la clave maestra en Laravel. Crea con ella una clave para la aplicación que solo pueda tocar los índices con su prefijo,
radios_*en este caso. En kenodo.com, la clave de su chat solo puede buscar, guardar documentos, crear índices y cambiar su configuración dentro de los índiceskenodo_*, así que no puede leer los índices de las otras aplicaciones del mismo servidor. - El acceso: Meilisearch no debería estar abierto a internet. Si está en otro servidor, ponlo detrás de HTTPS y deja entrar solo a las máquinas de tus aplicaciones.
El comando larachat:index sigue programado igual que en el primer tutorial, y conviene ejecutarlo también después de cada despliegue.
Tests
En el primer tutorial los tests no necesitaban nada externo. Ahora queremos comprobar que Meilisearch guarda y encuentra los fragmentos, así que los tests usarán el Meilisearch de Docker y seguirán simulando OpenAI con Http::fake().
Cada test trabaja en un índice con un prefijo aleatorio y lo borra al terminar, de modo que nunca toca los datos de desarrollo. Si Meilisearch no está en marcha, los tests se saltan con un aviso en lugar de fallar:
protected function setUp(): void
{
parent::setUp();
config([
'larachat.openai.api_key' => 'clave-de-mentira',
'larachat.openai.embedding_dimensions' => 3,
'larameili.prefix' => 'test_'.Str::lower(Str::random(6)).'_',
]);
try {
MeiliChunk::client()->health();
} catch (Throwable) {
$this->markTestSkipped('Meilisearch no está en marcha: arráncalo con docker compose up -d.');
}
}
Los vectores de verdad tienen 512 dimensiones y los calcula OpenAI. En los tests usamos vectores de tres dimensiones calculados a mano: la primera marca lo que habla de precios, la segunda lo que habla del horario y la tercera es igual para todo. Es suficiente para comprobar que la parte semántica de la búsqueda distingue las páginas:
private function vectorFor(string $text): array
{
$text = Str::lower($text);
return [
Str::contains($text, ['€', 'cuesta']) ? 1.0 : 0.0,
Str::contains($text, ['horario', 'sábado', 'abrís']) ? 1.0 : 0.0,
0.1,
];
}
Con esos vectores, este test indexa la web en Meilisearch y comprueba que cada pregunta encuentra primero la página que le corresponde:
public function test_hybrid_search_finds_the_right_page(): void
{
$this->fakeOpenAi();
$this->artisan('larachat:index')->assertSuccessful();
$store = new MeilisearchStore;
$hours = $store->search('¿Abrís los sábados?', $this->vectorFor('¿Abrís los sábados?'), 'es', 3);
$prices = $store->search('¿Cuánto cuesta una puesta a punto?', $this->vectorFor('¿Cuánto cuesta una puesta a punto?'), 'es', 3);
$this->assertSame(route('contact'), $hours[0]['url']);
$this->assertSame(route('prices'), $prices[0]['url']);
}
Mientras preparaba este test aprendí algo sobre los vectores falsos. En la primera versión, la palabra "precio" también marcaba un texto como de precios, y la portada, que tiene un botón "Ver precios", acababa con el mismo vector que la pregunta y salía por delante de la página de precios. Con vectores falsos, lo que estás probando es tu función de mentira tanto como la búsqueda, así que conviene que sea muy precisa.
En el repositorio hay cuatro tests: el índice, la configuración del embedder sin clave de OpenAI, la búsqueda híbrida y una respuesta del chat construida con fragmentos de Meilisearch. Ejecútalos con Meilisearch en marcha:
php artisan test
Finalizando
Ya tienes un chatbot con IA que guarda lo que sabe de tu web en Meilisearch y busca en ella combinando palabras y significado. El resto del chat, desde el asistente hasta el panel de conversaciones, funciona exactamente igual que con el archivo, así que puedes cambiar de almacén en cualquier momento sin tocar nada más.
Si tu web es pequeña y no tienes ya un Meilisearch, el archivo del primer tutorial sigue siendo la opción más sencilla.
Recuerda que siempre puedes consultar el código completo de la aplicación en GitHub. Para el resto de opciones del chat, consulta la documentación de Larachat.
Esto ha sido todo. Espero que este tutorial te haya resultado útil.