From b77d275fe0d7da9eaa227de6096ea4bfb0710897 Mon Sep 17 00:00:00 2001 From: Carlos Tello Date: Mon, 21 Sep 2026 10:09:46 -0300 Subject: [PATCH] Update project documentation --- README.md | 182 +++++++++++++++++++++++++++++++----------------------- 1 file changed, 106 insertions(+), 76 deletions(-) diff --git a/README.md b/README.md index b43703e..4178b9d 100644 --- a/README.md +++ b/README.md @@ -1,92 +1,122 @@ -# LLM Server - Deployment Automatizado +# LLM Server -Sistema completo de IA agentica con LLMs locales (Phi + DeepSeek 33B) en Ubuntu 22.04. +Despliegue automatizado de un servidor LLM local con Ollama, LiteLLM y +OpenClaw sobre Ubuntu 22.04/24.04. -## Requisitos Mínimos +## Requisitos -- **CPU**: Intel i3-10105 (4 cores) -- **RAM**: 16GB DDR4 -- **GPU**: NVIDIA RTX 3090 (24GB VRAM) -- **PSU**: 850W+ -- **SO**: Ubuntu 22.04 LTS +- Ubuntu 22.04 o 24.04 +- CPU de 4 núcleos o superior +- 16 GB de RAM como mínimo +- GPU NVIDIA compatible con sus controladores Linux +- Acceso `sudo` y conexión a Internet -## Solución para tool calling con rutas de Windows +La configuración está orientada a una NVIDIA RTX 3090 de 24 GB, pero el +script puede utilizarse con otras GPU compatibles ajustando el modelo si es +necesario. -Cuando el LLM intenta ejecutar una herramienta, la respuesta no debe mostrarse como texto plano. Debe ser manejada como un `tool_call` o `function_call` y ejecutada localmente. +## Instalación -### Regla importante - -Añade esta instrucción al `System Prompt`: - -```text -When outputting Windows file paths in JSON arguments, you must strictly escape all backslashes (for example: C:\\Users\\name\\file.txt). -``` - -### Patrón recomendado - -1. El LLM devuelve una llamada como JSON. -2. Tu cliente detecta `tool_calls` o `function_call`. -3. Tu código ejecuta la función localmente. -4. Se envía de vuelta al LLM el resultado con rol `tool` o `function`. - -### Ejemplo de implementación - -El proyecto incluye un ejemplo funcional en `tool_call_demo.py` que: - -- simula un `tool_call` del modelo, -- valida que la ruta JSON esté escapada correctamente, -- lee el archivo físico en disco, -- devuelve el contenido al modelo para continuar. +Clona el repositorio en el servidor: ```bash -python tool_call_demo.py -``` - -### Ejemplo de payload válido - -```json -{ - "tool_calls": [ - { - "id": "call_read_001", - "type": "function", - "function": { - "name": "read_file", - "arguments": "{\"path\": \"c:\\\\Workspace\\\\llm-server-setup\\\\README.md\"}" - } - } - ] -} -``` - -> Si el JSON tiene barras invertidas sin escape, el parser falla y el modelo parece "no responder". Usar rutas con `\\` en JSON es obligatorio en Windows. - -## Instalación Rápida - -```bash -# 1. Clonar repositorio -git clone https://github.com/tuuser/llm-server-setup.git +git clone https://gitea.oemspot.com.ar/carlostellocba/llm-server-setup.git cd llm-server-setup - -# 2. Instalar OpenClaw sin iniciar el asistente -bash install_openclaw.sh - -# 3. Ejecutar el asistente inicial cuando quieras -openclaw onboard --install-daemon - -# También puedes instalar y abrir el asistente en el mismo paso -bash install_openclaw.sh --onboard ``` -El script está pensado para Ubuntu 22.04/24.04 y WSL2. Usa el instalador oficial -de OpenClaw, que instala Node.js si es necesario. Revisa las instrucciones -oficiales si vas a usar otra distribución o un entorno restringido. - -## Instalación del servidor LLM +Ejecuta el instalador principal como `root` o mediante `sudo`: ```bash -nano setup_llm_server.sh - chmod +x setup_llm_server.sh sudo ./setup_llm_server.sh ``` + +El instalador: + +- actualiza los paquetes del sistema e instala dependencias; +- configura un archivo de swap de 8 GB; +- instala los controladores NVIDIA si no están disponibles; +- instala y configura Ollama en `0.0.0.0:11434`; +- crea un entorno virtual de LiteLLM en `/opt/litellm-env`; +- descarga `qwen2.5-coder:14b`; +- crea el servicio `litellm.service` en el puerto `8000`; +- permite SSH y LiteLLM mediante UFW. + +El proceso puede tardar varios minutos y requiere espacio suficiente para el +modelo. Si se instalan controladores NVIDIA nuevos, reinicia el servidor: + +```bash +sudo reboot +``` + +## Verificación + +Después de la instalación, comprueba los servicios: + +```bash +systemctl status ollama +systemctl status litellm +nvidia-smi +curl http://127.0.0.1:11434/api/tags +curl http://127.0.0.1:8000/health/liveliness +``` + +La configuración de LiteLLM se genera en el directorio personal del usuario +que ejecuta `sudo` y queda guardada como `~/litellm_config.yaml`. + +## Instalación de OpenClaw + +El script `install_openclaw.sh` utiliza el instalador oficial de OpenClaw y +está pensado para Linux y WSL2. Para instalarlo sin abrir el asistente inicial: + +```bash +bash install_openclaw.sh +``` + +Para instalarlo y ejecutar el asistente inmediatamente: + +```bash +bash install_openclaw.sh --onboard +``` + +Si la instalación se hizo sin asistente, puedes iniciarlo después y configurar +el servicio de Gateway: + +```bash +openclaw onboard --install-daemon +``` + +Comprueba la instalación con: + +```bash +openclaw --version +openclaw doctor +openclaw gateway status +``` + +## Tool calling y rutas de Windows + +Cuando un modelo envía rutas de Windows dentro de argumentos JSON, las barras +invertidas deben estar escapadas. Por ejemplo: + +```json +{ + "path": "C:\\Users\\name\\file.txt" +} +``` + +Si las barras no están escapadas, el parser JSON puede fallar antes de que la +herramienta llegue a ejecutarse. + +## Archivos principales + +- `setup_llm_server.sh`: instala y configura Ollama, LiteLLM, NVIDIA y UFW. +- `install_openclaw.sh`: instala OpenClaw mediante el instalador oficial. +- `litellm_config.yaml`: configuración local opcional para LiteLLM. +- `tool_call_demo.py`: ejemplo local de manejo de llamadas a herramientas. + +## Seguridad + +El instalador expone Ollama en todas las interfaces y abre el puerto `8000` +en UFW. En un servidor conectado a Internet, limita esos puertos a la red +privada o protégelos detrás de un proxy con autenticación y HTTPS. \ No newline at end of file