Cambiar el modelo de indexación de documentos#

Esta guía explica cómo cambiar el modelo que crea los vectores para buscar en los documentos. Al cambiar el modelo o la dimensión de los vectores, Sherpa AI Server elimina los vectores anteriores y vuelve a indexar los documentos. La búsqueda por contenido puede no estar disponible durante el cambio, y los resultados pueden estar incompletos hasta que termine el procesamiento de los archivos. Programe el cambio para un momento adecuado. Los nombres de navegación se traducen en esta guía; la interfaz de la versión 2.5.1 está disponible en ruso e inglés. A continuación, los estados y el botón de reindexación se citan como aparecen en la interfaz inglesa.

Antes de empezar#

• Para modificar estos ajustes se necesitan los permisos documents:update y ai_models:read. Para crear un modelo o una instancia también se necesita ai_models:create. Configurar una instancia de vLLM mediante la API requiere ai_models:update.
• Averigüe la dimensión real de los vectores del nuevo modelo. Introduzca el número que devuelve: un entero de 32 a 2000. Al actualizar de 2.5.0 a 2.5.1, prepare los índices 384 y 1024. Si la versión actual es anterior a 2.5.0, acuerde primero la ruta de actualización con el equipo de soporte. Para cualquier otra dimensión, un administrador debe preparar primero el índice de búsqueda.
• Un modelo de tipo Indexación o Multimodal debe tener exactamente una instancia activa. Varias instancias del mismo modelo pueden devolver vectores incompatibles.
• No cambie la dirección o la ruta de la instancia activa del modelo de indexación actual para dirigirla a otra fuente de vectores: el sistema rechaza ese cambio. Cree un modelo y una instancia nuevos; después, seleccione el nuevo modelo en los ajustes de indexación de documentos.
• Si los documentos contienen fragmentos añadidos solo mediante la API, sin un archivo de origen, consulte «Si se rechaza el cambio» más abajo. La reindexación normal no puede restaurar esos fragmentos.

Ejemplo: BGE-M3 mediante vLLM#

En un servidor con GPU, inicie una instancia independiente de vLLM para el modelo de indexación. Este ejemplo utiliza vLLM 0.27.1 y BAAI/bge-m3 (vLLM debe estar instalado y los archivos del modelo deben estar disponibles):

vllm serve BAAI/bge-m3 --runner pooling --pooler-config.task embed \
  --hf-overrides '{"architectures":["BgeM3EmbeddingModel"]}' \
  --host 0.0.0.0 --port 8001

En el servidor vLLM, compruebe que cada vector contiene 1024 números (se necesita jq):

curl -fsS http://127.0.0.1:8001/v1/embeddings \
  -H 'Content-Type: application/json' \
  -d '{"model":"BAAI/bge-m3","input":["test"]}' \
  | jq '.data[0].embedding | length'

En Modelos, cree un modelo nuevo de tipo Indexación y una sola instancia local activa. Indique BAAI/bge-m3 como ruta del modelo, 8001 como puerto y una dirección de vLLM accesible desde el contenedor de Sherpa AI Server. Si vLLM se ejecuta en otro servidor, utilice su nombre de red o dirección IP. 127.0.0.1 dentro del contenedor de Sherpa hace referencia a ese mismo contenedor. Deje vacía la ruta adicional de la API.

Antes de seleccionar este modelo para la indexación, configure la instancia mediante la API de Sherpa AI Server con el permiso ai_models:update: solicite GET /api/v1/models/{model_guid}/instances/{instance_guid}, copie el objeto data.connection_params completo, añada "embed_format": "openai" y envíe el objeto completo actualizado mediante PATCH a la misma dirección como {"connection_params": {…}}. Repita GET y confirme que data.connection_params.embed_format es openai. PATCH sustituye todo el objeto de parámetros: conserve todos los campos existentes de conexión y autenticación.

Esta configuración dirige las solicitudes de Sherpa a /v1/embeddings. Sin ella, una instancia local utiliza /v2/embed con un valor input_type que BGE-M3 rechaza en vLLM 0.27.1. Después de configurar la instancia, no la guarde desde el formulario Modelos: el formulario no muestra embed_format y lo elimina al guardar. La prueba de conexión del formulario solo comprueba la disponibilidad del servidor; Sherpa comprueba los vectores reales al guardar los ajustes de indexación. Después, siga los pasos siguientes para seleccionar el nuevo modelo y la dimensión 1024.

Cambiar el modelo#

1. Abra Modelos y compruebe que el modelo deseado y su única instancia activa estén disponibles. Si el modelo no existe y tiene ai_models:create, pulse Crear en la lista de modelos, cree un modelo de tipo Indexación o Multimodal, pulse Crear en la lista de instancias y añada una instancia. De lo contrario, contacte con un administrador.
2. Abra Documentos → Ajustes → Indexación. Seleccione el Modelo de indexación e introduzca su Dimensión del embedding real. Cambiar solo el número no cambia el modelo.
3. Pulse Guardar una vez. El servidor comprueba el modelo, la dimensión que devuelve y si el índice de búsqueda está preparado. Tras una comprobación satisfactoria, guarda el nuevo modelo y la dimensión, elimina los vectores anteriores y pone en cola los documentos configurados para la indexación automática. Los archivos originales se conservan. No es necesario pulsar Delete all vectors and reindex por separado. Seleccionar otro modelo también inicia el cambio aunque la dimensión siga siendo la misma.
4. Espere a que se procesen los documentos: Pending → Processing → Ready. Si un archivo muestra Awaiting manual indexing, ábralo y pulse Re-index; después, espere a que aparezca Ready. Los archivos con estado Not indexed no se indexan. El servidor reindexa automáticamente los ejemplos de respuestas de los asistentes.
5. Busque contenido de un documento conocido y confirme que los archivos necesarios hayan llegado a Ready. Si un archivo muestra Error, consulte y resuelva la causa. Después, pulse Re-index para ese archivo. Para volver a procesar todos los archivos, use Delete all vectors and reindex por separado.

Ejemplos#

• 384 → 1024. Seleccione un nuevo modelo que devuelva vectores de dimensión 1024, introduzca 1024 y pulse Guardar. Espere a que se reindexen los archivos y compruebe la búsqueda.
• 1024 → 384. Seleccione un modelo que devuelva vectores de dimensión 384, introduzca 384 y siga los mismos pasos.
• 384 → 384, otro modelo. Seleccione otro modelo, mantenga 384 y pulse Guardar. El cambio de modelo inicia la reindexación aunque la dimensión no cambie.

Si se rechaza o interrumpe el cambio#

Si falla la comprobación previa porque el modelo no está disponible, la dimensión es incorrecta o el índice no está preparado, corrija la causa y vuelva a guardar. Si el cambio se rechaza debido a fragmentos añadidos solo mediante la API, se conservan el modelo, la dimensión y los vectores anteriores. Guarde el texto y los metadatos de esos fragmentos fuera del sistema; después, pida a un administrador que los elimine o elimine el archivo que los contiene si ya no es necesario. Tras completar el cambio de modelo, vuelva a añadir los fragmentos guardados mediante la API si hace falta.

Si la transición ya comenzó, pero sigue pendiente o se interrumpió, vuelva a abrir los ajustes y guarde el mismo modelo y la misma dimensión. El servidor completará la limpieza y pondrá los archivos en cola; la indexación se ejecutará en segundo plano. No seleccione otra pareja de modelo y dimensión mientras la transición no haya terminado.

Si también cambió los ajustes de reconocimiento de PDF, el tamaño de los fragmentos o su solapamiento, vuelva a abrir los ajustes después de un error y compruebe esos campos: podrían haberse guardado por separado. Esto no significa que el cambio de modelo y dimensión se haya completado correctamente.

Para administradores: otra dimensión#

Para una dimensión distinta de 384 o 1024, prepare el índice de la cuenta después de las migraciones de la versión 2.5.1 y antes de guardar el nuevo modelo. El SQL completo, las comprobaciones y los comandos para la instalación estándar del cliente se encuentran en la sección «Dimensiones adicionales después de la actualización» de la guía de preparación de índices. Copie el SQL desde esa página a un archivo local e indique el ID numérico de la cuenta y la dimensión real del modelo. Cuando el comando termine correctamente, el usuario puede pulsar Guardar.