Update project documentation
This commit is contained in:
Carlos Tello
@@ -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.
|
||||
Reference in New Issue
Block a user