Instalación de Sherpa AI Server#

Antes de comenzar#

Se necesita un servidor con Docker y Docker Compose v2, espacio suficiente para archivos, modelos y contenedores, y acceso a la distribución o un conjunto completo de archivos transferidos previamente. Para un LLM local, elija un servidor con GPU o la instalación solo con CPU. Prepare el nombre de dominio, la dirección IP y los certificados SSL. Si el LLM se ejecuta en otro equipo, consulte la conexión a un servidor LLM independiente.

Descargue el archivo client-files de la versión publicada que necesite y su archivo de suma de comprobación. Es necesario verificar SHA-256 según la guía de descarga de la distribución. Todos los archivos de imágenes Docker deben ser de la misma versión. El instalador comprueba la versión, las sumas y las etiquetas de las imágenes antes de iniciar los contenedores. No seleccione archivos de manera independiente con latest ni ejecute load_all_docker_images.sh: ese script auxiliar antiguo selecciona el archivo más reciente de cada imagen por separado.

Si el servidor no puede acceder al servidor de descargas, transfiera client-files, los archivos de imágenes necesarios y los archivos .SHA256SUM correspondientes a un mismo directorio. La guía de descarga explica el conjunto necesario y cómo comprobar el espacio disponible en disco.

Instalación mediante el script#

El ejemplo utiliza la versión 2.5.1. Es necesario indicar el nombre del archivo que ya haya verificado y ejecute estos comandos en el directorio de instalación:

CLIENT_ARCHIVE=docker_aiserver_client_files_2.5.1.tgz
tar -xzf "$CLIENT_ARCHIVE"
chmod +x sh_scripts/*.sh
sudo ./sh_scripts/install.sh

El instalador realiza los siguientes pasos:

1. Comprueba Docker, Docker Compose v2, el archivo .env y la versión APP_VERSION incluida en el paquete.
2. Ofrece el modo GPU (vLLM), CPU (llama.cpp) o LLM y Embedding externos, los servicios opcionales Whisper y BGE Reranker, y un modelo LLM disponible. Whisper y reranker requieren una GPU. Si elige varios modelos, tenga en cuenta la memoria de vídeo disponible.
3. Encuentra los archivos necesarios de imágenes Docker para APP_VERSION. Si hay conexión, descarga los archivos faltantes, verifica SHA-256 y las etiquetas del manifiesto Docker, carga las imágenes y extrae los modelos elegidos. Sin acceso, informa de los archivos que faltan.
4. Crea una copia de seguridad de .env y solicita HOST_IP, NGINX_DOMAIN_NAME, MAX_TOKENS_MESSAGE, la contraseña de PostgreSQL, el modelo y otros ajustes. Sustituya la contraseña predeterminada por una contraseña única y segura. No guarde contraseñas en notas sin protección. El instalador restringe el acceso a .env.
5. Ofrece HTTPS para el servidor principal y la conexión con el servidor de embeddings. Prepare certificados y claves de confianza. En un servidor de pruebas pueden utilizarse certificados autofirmados. Consulte la guía de SSL para más detalles.
6. Muestra los ajustes finales y el plan de inicio de Docker Compose. Es necesario comprobar el modo, el modelo, el dominio y los perfiles, y confirme el inicio.

El instalador guarda los perfiles elegidos en COMPOSE_PROFILES. Si la instalación se interrumpe, resuelva la causa indicada y vuelva a ejecutar install.sh. No mezcle archivos de distintas versiones para eludir una comprobación fallida.

LLM y Embedding externos#

Utilice esta opción cuando ambos servicios ya se ejecuten en otro servidor. El servidor principal necesita acceso de red a sus API. El LLM debe ofrecer una API compatible y Embedding debe ofrecer la API de Sherpa Embedding. Prepare certificados de confianza para HTTPS. Si Embedding requiere un token, solicítelo al administrador del servicio antes de instalar.

1. Ejecute sudo ./sh_scripts/install.sh desde el directorio de instalación y seleccione [3] LLM y Embedding externos.
2. Indique la dirección del LLM, por ejemplo http://llm.example.local:8000, la de Embedding, por ejemplo https://embed.example.local:443, y el nombre del modelo devuelto por la API del LLM. Indique el token de Embedding si se requiere autenticación. No incluya /v1 en las direcciones.
3. En el paso de archivos, proporcione solo las imágenes solicitadas por el instalador. No se necesitan imágenes ni archivos de modelos de LLM y Embedding locales.
4. Compruebe el resumen y la lista de servicios. .env debe contener COMPOSE_PROFILES=external. El comando docker compose --profile external config --services no debe mostrar aiserver-embed, aiserver-llm-server ni aiserver-llm-server-cpu.
5. Después del inicio, compruebe docker compose ps, abra Chat y envíe una solicitud de prueba. Compruebe la búsqueda de documentos si la utiliza. La respuesta y los resultados de búsqueda confirman la conexión con los servicios externos.

El instalador guarda las URL, los hosts, los puertos, el esquema de LLM y el nombre del modelo en .env. Si cambia la dirección de LLM, actualice su URL, host, puerto y esquema en .env. Después, abra la instancia correspondiente en Modelos y actualice los campos Host, Puerto y Esquema: el Chat usa los parámetros guardados en la instancia. Si cambia la dirección o el token de Embedding, actualice también .env. Después de editar .env, ejecute docker compose up -d --force-recreate aiserver: un restart normal no vuelve a cargar las variables de entorno. Si fallan las solicitudes, compruebe el acceso de red desde el servidor principal y los registros de aiserver. El actualizador conserva el modo externo y no requiere las imágenes ni los modelos locales de estos servicios.

Servicios y perfiles#

Los servicios principales se inician sin un perfil adicional:

Los perfiles adicionales seleccionan el LLM y los servicios de procesamiento:

Si administra los perfiles manualmente, indique solo los servicios elegidos. Por ejemplo, GPU con Whisper:

docker compose --profile embed --profile gpu --profile whisper up -d

Para CPU sin GPU:

docker compose --profile embed --profile cpu up -d

Comprobación de la instalación#

Para diagnosticar la instalación, el administrador necesita acceso a Docker Compose en el servidor. Desde el directorio que contiene .env y docker-compose.yml, ejecute:

sudo ./sh_scripts/diagnostics.sh

El script comprueba los contenedores principales, la LLM local, Whisper y BGE Reranker si sus perfiles están activados, PostgreSQL, el espacio libre y la respuesta de la API. Si todo funciona, muestra Диагностика завершена без замечаний y devuelve el código 0. Si falla, indica el componente afectado y devuelve el código 1. Para obtener detalles, ejecute el comando docker compose logs indicado en el mensaje.

Para que el asistente de instalación ofrezca el diagnóstico después de un inicio correcto, ejecútelo con SHERPA_DIAGNOSTICS_OFFER=true. Ejemplo: sudo env SHERPA_DIAGNOSTICS_OFFER=true ./sh_scripts/install.sh. De forma predeterminada no aparece la pregunta. El diagnóstico no modifica los datos de la instalación.

Es necesario comprobar el estado de los contenedores y los registros. Los servicios en ejecución deben tener el estado Up:

docker compose ps
docker compose logs --tail=100 aiserver

Es necesario abrir https://<su-dominio> en un navegador y compruebe que puede iniciar sesión. Para comprobar la respuesta del servidor web, sustituya el dominio de ejemplo por el suyo:

curl -I https://aiserver.example.com

Se espera una respuesta HTTP satisfactoria o una redirección a la página de inicio de sesión. Es necesario comprobar que el navegador confía en el certificado sin mostrar advertencias. Si utiliza un LLM local, envíe un mensaje de prueba en el chat y confirme que el modelo responde. Si hay problemas, consulte los registros del servicio correspondiente:

docker compose logs --tail=100 aiserver-llm-server
docker compose logs --tail=100 aiserver-embed

En el modo CPU, utilice aiserver-llm-server-cpu en lugar de aiserver-llm-server. Si un contenedor no se inicia, compruebe el espacio en disco y los registros. Si hay errores de acceso o de base de datos, compruebe .env. Para HTTPS, compruebe los certificados y el dominio. Para GPU, compruebe el controlador, la disponibilidad de la tarjeta y la VRAM.

Mantenimiento#

Ejecute los comandos desde el directorio que contiene docker-compose.yml y .env:

docker compose ps
docker compose logs -f aiserver
docker compose restart aiserver
docker stats

Para GPU, utilice también nvidia-smi. docker compose down detiene y elimina los contenedores; no añada -v si desea conservar los datos de los volúmenes Docker. Para actualizar, utilice la guía de actualización. Antes de actualizar de 2.5.0 a 2.5.1, complete la preparación de índices. Si la versión actual es anterior a 2.5.0, acuerde con el equipo de soporte la ruta de actualización.