# LMDeploy

**Kit de herramientas eficiente para el despliegue de LLM por Shanghai AI Lab** — inferencia, cuantización y servicio de grado de producción para modelos de lenguaje grandes con batching continuo y PagedAttention.

> 🏛️ Desarrollado por **OpenMMLab / Shanghai AI Lab** | Licencia Apache-2.0 | 4.000+ estrellas en GitHub

***

## ¿Qué es LMDeploy?

LMDeploy es un conjunto de herramientas integral para comprimir, desplegar y servir Modelos de Lenguaje Grande en producción. Construido por el mismo equipo detrás de OpenMMLab (MMDetection, MMSeg), aporta optimizaciones de nivel de investigación al despliegue práctico:

* **Motor TurboMind** — backend de inferencia de alto rendimiento en C++ con optimizaciones CUDA
* **Motor PyTorch** — motor flexible basado en Python para amplia compatibilidad de modelos
* **Batching continuo** — maximiza la utilización de la GPU entre solicitudes concurrentes
* **PagedAttention** — gestión eficiente de la caché KV (similar a vLLM)
* **Cuantización de 4 bits / 8 bits** — soporte para AWQ y SmoothQuant
* **Modelos Visión-Lenguaje** — soporte para InternVL, LLaVA, Qwen-VL

Comparado con vLLM, el motor TurboMind de LMDeploy ofrece \~1.36× mayor rendimiento en Llama 3 8B con batch=32, y su cuantización AWQ es de primera clase — no una ocurrencia tardía. Para VLMs (especialmente InternVL2), LMDeploy es la pila de despliegue de referencia.

### ¿Por qué LMDeploy?

| Característica                  | LMDeploy | vLLM     | TGI      |
| ------------------------------- | -------- | -------- | -------- |
| Batching continuo               | ✅        | ✅        | ✅        |
| Cuantización AWQ                | ✅        | ✅        | ❌        |
| Decodificación especulativa     | ✅        | ✅        | ✅        |
| Visión-Lenguaje                 | ✅        | Limitado | Limitado |
| API de OpenAI                   | ✅        | ✅        | ✅        |
| TurboMind (motor personalizado) | ✅        | ❌        | ❌        |

***

## Inicio rápido en Clore.ai

### Paso 1: Seleccionar un servidor GPU

En [clore.ai](https://clore.ai) mercado:

* **Mínimo:** GPU NVIDIA con 8GB de VRAM (para modelos 7B)
* **Recomendado:** RTX 3090/4090 (24GB) o A100 (40/80GB)
* **CUDA:** Se requiere 11.8 o 12.x

### Paso 2: Desplegar LMDeploy Docker

```
Imagen Docker: openmmlab/lmdeploy
```

**Mapeos de puertos:**

| Puerto del contenedor | Propósito                |
| --------------------- | ------------------------ |
| `22`                  | Acceso SSH               |
| `23333`               | Servidor API de LMDeploy |

**Variables de entorno:**

```
HUGGING_FACE_HUB_TOKEN=tu_token_hf_aquí  # Para modelos con acceso restringido
```

### Paso 3: SSH y Verificación

```bash
ssh root@<clore-node-ip> -p <ssh-port>

# Verificar instalación
python -c "import lmdeploy; print(lmdeploy.__version__)"
lmdeploy --help
```

***

## Iniciando el Servidor API

### Servidor compatible con OpenAI (Recomendado)

```bash
# Servir Llama 3 8B con el motor TurboMind
lmdeploy serve api_server \
  meta-llama/Meta-Llama-3-8B-Instruct \
  --server-port 23333 \
  --server-name 0.0.0.0 \
  --model-name llama3-8b

# Con selección explícita de motor
lmdeploy serve api_server \
  meta-llama/Meta-Llama-3-8B-Instruct \
  --backend turbomind \
  --server-port 23333 \
  --server-name 0.0.0.0 \
  --tp 1 \
  --max-batch-size 128 \
  --cache-max-entry-count 0.8
```

### Motor PyTorch (Mayor compatibilidad)

```bash
# Use el motor PyTorch para modelos no soportados por TurboMind
lmdeploy serve api_server \
  mistralai/Mistral-7B-Instruct-v0.2 \
  --backend pytorch \
  --server-port 23333 \
  --server-name 0.0.0.0
```

### Salida de inicio del servidor

```
[2024-01-01 12:00:00,000] INFO: Cargando modelo: meta-llama/Meta-Llama-3-8B-Instruct
[2024-01-01 12:00:20,000] INFO: Motor TurboMind inicializado
[2024-01-01 12:00:20,000] INFO: Servidor iniciado en http://0.0.0.0:23333
[2024-01-01 12:00:20,000] INFO: Documentación API: http://0.0.0.0:23333/docs
```

{% hint style="success" %}
Una vez iniciado, LMDeploy expone documentación API interactiva en `http://<tu-ip>:23333/docs` — útil para probar endpoints directamente desde el navegador.
{% endhint %}

***

## Modelos compatibles

### Modelos de texto

```bash
# Llama 3
meta-llama/Meta-Llama-3-8B-Instruct
meta-llama/Meta-Llama-3-70B-Instruct

# Mistral / Mixtral
mistralai/Mistral-7B-Instruct-v0.2
mistralai/Mixtral-8x7B-Instruct-v0.1

# Qwen
Qwen/Qwen2-7B-Instruct
Qwen/Qwen2-72B-Instruct

# InternLM
internlm/internlm2-chat-7b
internlm/internlm2-chat-20b

# Yi
01-ai/Yi-1.5-9B-Chat
01-ai/Yi-1.5-34B-Chat

# Gemma
google/gemma-7b-it
google/gemma-2b-it
```

### Modelos Visión-Lenguaje

```bash
# InternVL (VLM recomendado)
OpenGVLab/InternVL2-8B
OpenGVLab/InternVL2-26B

# LLaVA
llava-hf/llava-1.5-7b-hf

# Qwen-VL
Qwen/Qwen-VL-Chat
```

***

## Cuantización

### Cuantización AWQ de 4 bits

El AWQ (Activation-aware Weight Quantization) de LMDeploy produce una excelente calidad en 4 bits:

```bash
# Cuantizar un modelo a AWQ 4-bit
lmdeploy lite auto_awq \
  meta-llama/Meta-Llama-3-8B-Instruct \
  --calib-dataset ptb \
  --calib-samples 128 \
  --calib-seqlen 2048 \
  --w-bits 4 \
  --w-group-size 128 \
  --work-dir ./quantized/llama3-8b-awq

# Servir el modelo cuantizado
lmdeploy serve api_server \
  ./quantized/llama3-8b-awq \
  --server-port 23333 \
  --server-name 0.0.0.0
```

### SmoothQuant W8A8

Cuantización de pesos y activaciones a 8 bits (mejor para despliegues críticos en rendimiento):

```bash
lmdeploy lite smooth_quant \
  meta-llama/Meta-Llama-3-8B-Instruct \
  --work-dir ./quantized/llama3-8b-sq \
  --calib-dataset ptb \
  --calib-samples 512
```

### Impacto de la cuantización

| Cuantización     | VRAM (7B) | Pérdida de calidad | Ganancia de rendimiento |
| ---------------- | --------- | ------------------ | ----------------------- |
| Ninguna (bf16)   | \~14GB    | Ninguna            | Referencia              |
| SmoothQuant W8A8 | \~8GB     | Mínima             | +20%                    |
| AWQ W4A16        | \~4GB     | Baja               | +15%                    |
| GPTQ W4A16       | \~4GB     | Baja               | +10%                    |

{% hint style="info" %}
**Recomendación AWQ:** Para la mayoría de los casos de uso, AWQ 4-bit es el mejor equilibrio entre calidad y ahorro de VRAM. Use `--w-group-size 128` para mejor calidad con un uso de memoria ligeramente mayor.
{% endhint %}

***

## Ejemplos de uso de la API

### Cliente Python

```python
from openai import OpenAI

client = OpenAI(
    base_url="http://<ip-nodo-clore>:<puerto-api>/v1",
    api_key="none"
)

# Completado de chat
response = client.chat.completions.create(
    model="llama3-8b",
    messages=[
        {"role": "system", "content": "Eres un asistente útil."},
        {"role": "user", "content": "Resume la historia de la IA en 3 frases."}
    ],
    temperature=0.7,
    max_tokens=512
)
print(response.choices[0].message.content)
```

### Streaming

```python
stream = client.chat.completions.create(
    model="llama3-8b",
    messages=[{"role": "user", "content": "Escribe un poema sobre el espacio."}],
    stream=True
)

for chunk in stream:
    delta = chunk.choices[0].delta
    if delta.content:
        print(delta.content, end="", flush=True)
print()
```

### Cliente Python nativo de LMDeploy

```python
from lmdeploy import pipeline, TurbomindEngineConfig

# Pipeline directo (no se necesita servidor)
pipe = pipeline(
    'meta-llama/Meta-Llama-3-8B-Instruct',
    backend_config=TurbomindEngineConfig(max_batch_size=16)
)

# Inferencia única
response = pipe("¿Cuál es la capital de Francia?")
print(response.text)

# Inferencia por lotes
responses = pipe([
    "Explica la gravedad",
    "¿Qué es el ADN?",
    "¿Cómo funciona Bitcoin?"
])
for r in responses:
    print(r.text)
    print("---")
```

### Modelo Visión-Lenguaje

```python
from lmdeploy import pipeline
from lmdeploy.vl import load_image

pipe = pipeline('OpenGVLab/InternVL2-8B')

image = load_image('https://example.com/photo.jpg')
response = pipe(('Describe esta imagen en detalle', image))
print(response.text)
```

***

## Despliegue multi-GPU

### Paralelismo tensorial

```bash
# Distribuir un modelo 70B en 4 GPUs
lmdeploy serve api_server \
  meta-llama/Meta-Llama-3-70B-Instruct \
  --backend turbomind \
  --server-port 23333 \
  --server-name 0.0.0.0 \
  --tp 4 \
  --max-batch-size 64
```

```python
from lmdeploy import pipeline, TurbomindEngineConfig

pipe = pipeline(
    'meta-llama/Meta-Llama-3-70B-Instruct',
    backend_config=TurbomindEngineConfig(tp=4)
)
```

***

## Configuración avanzada

### Configuración del motor TurboMind

```python
from lmdeploy import pipeline, TurbomindEngineConfig

engine_config = TurbomindEngineConfig(
    max_batch_size=64,          # Máximo de solicitudes concurrentes
    cache_max_entry_count=0.8,  # Ratio de caché KV (0.0-1.0)
    quant_policy=0,             # 0=sin cuantización, 4=cache KV a 4bit, 8=cache KV a 8bit
    rope_scaling_factor=1.0,    # Para contexto extendido
    num_tokens_per_iter=4096,   # Tamaño del chunk de prellenado
    max_prefill_token_num=8192, # Longitud máxima de prellenado
)

pipe = pipeline('meta-llama/Meta-Llama-3-8B-Instruct', backend_config=engine_config)
```

### Configuración de generación

```python
from lmdeploy import GenerationConfig

gen_config = GenerationConfig(
    temperature=0.7,
    top_p=0.9,
    top_k=40,
    repetition_penalty=1.1,
    max_new_tokens=1024,
    stop_words=['<|eot_id|>', '<|end_of_text|>'],
)

response = pipe("¡Hola, mundo!", gen_config=gen_config)
```

***

## Monitoreo y métricas

### Comprobar la salud del servidor

```bash
# Endpoint de health check
curl http://localhost:23333/health

# Lista los modelos disponibles
curl http://localhost:23333/v1/models

# Estadísticas del servidor
curl http://localhost:23333/stats
```

### Monitoreo de GPU

```bash
# Estadísticas de GPU en tiempo real
watch -n 1 'nvidia-smi --query-gpu=name,memory.used,memory.free,utilization.gpu --format=csv'
```

***

## Ejemplo Docker Compose

```yaml
version: '3.8'
services:
  lmdeploy:
    image: openmmlab/lmdeploy:latest
    runtime: nvidia
    environment:
      - NVIDIA_VISIBLE_DEVICES=all
      - HUGGING_FACE_HUB_TOKEN=${HF_TOKEN}
    ports:
      - "23333:23333"
      - "22:22"
    volumes:
      - hf-cache:/root/.cache/huggingface
      - ./models:/models
    command: >
      lmdeploy serve api_server
      meta-llama/Meta-Llama-3-8B-Instruct
      --server-port 23333
      --server-name 0.0.0.0
      --model-name llama3-8b
      --max-batch-size 64
    restart: unless-stopped
    shm_size: '2g'

volumes:
  hf-cache:
```

***

## Benchmarking

```bash
# Herramienta de benchmark incorporada
lmdeploy benchmark \
  meta-llama/Meta-Llama-3-8B-Instruct \
  --backend turbomind \
  --concurrency 1 4 8 16 32 \
  --num-prompts 1000 \
  --prompt-len 128 \
  --output-len 256
```

Salida de ejemplo (RTX 4090, TurboMind, bf16):

```
concurrency=1:  throughput=42.3 tokens/s, latency_p50=23ms
concurrency=8:  throughput=287.1 tokens/s, latency_p50=156ms
concurrency=32: throughput=412.6 tokens/s, latency_p50=621ms
```

En A100 80GB, espere \~2.2× mayor rendimiento vs RTX 4090 en alta concurrencia debido al ancho de banda de memoria HBM2e (2 TB/s vs 1 TB/s).

***

## Recomendaciones de GPU en Clore.ai

Elija según el tamaño de modelo objetivo y la carga de servicio:

| Caso de uso                             | GPU           | VRAM  | Por qué                                                              |
| --------------------------------------- | ------------- | ----- | -------------------------------------------------------------------- |
| Modelos 7–13B, desarrollo/preproducción | **RTX 3090**  | 24 GB | Mejor relación $/VRAM; maneja 7B bf16 o 13B AWQ                      |
| Modelos 7–13B, producción               | **RTX 4090**  | 24 GB | \~40% más rápido que 3090 con la misma VRAM; 412 tok/s en Llama 3 8B |
| Modelos 70B, servicio por equipo        | **A100 40GB** | 40 GB | Ajusta 70B AWQ; memoria ECC para fiabilidad                          |
| Modelos 70B, alto rendimiento           | **A100 80GB** | 80 GB | Ajusta 70B bf16; 2× rendimiento vs A100 40GB con batch=32            |

**Opción económica:** RTX 3090 + AWQ 4-bit — sirve Llama 3 8B a \~280 tok/s batch=8, cubre la mayoría de casos de uso de API.

**Opción velocidad:** RTX 4090 — la más rápida por dólar para modelos 7–13B; TurboMind exprime cada GB/s de su ancho de banda de 1 TB/s.

**Opción producción:** A100 80GB — ejecuta Qwen2-72B o Llama 3 70B en bf16 completo sin compromisos de calidad por cuantización; encaja fácilmente en servicio multi-instancia de GPU.

***

## Solución de problemas

### Modelo no carga

```bash
# Compruebe que el token de HuggingFace está configurado
echo $HUGGING_FACE_HUB_TOKEN

# Descargar el modelo manualmente
pip install huggingface_hub
huggingface-cli download meta-llama/Meta-Llama-3-8B-Instruct --local-dir ./llama3-8b

# Usar ruta local en su lugar
lmdeploy serve api_server ./llama3-8b --server-port 23333
```

### CUDA Fuera de memoria

```bash
# Reducir la asignación de caché KV
lmdeploy serve api_server MODEL \
  --cache-max-entry-count 0.5  # Reducir desde 0.8

# Usar caché KV cuantizada
lmdeploy serve api_server MODEL \
  --quant-policy 8  # Caché KV a 8 bits
```

### Puerto ya en uso

```bash
# Compruebe qué está usando el puerto 23333
ss -tlnp | grep 23333
fuser 23333/tcp

# Matar proceso existente
kill -9 $(fuser 23333/tcp)
```

{% hint style="warning" %}
**Modo de red Docker:** Al ejecutar en Docker, asegúrese de que el contenedor use `--network host` o un mapeo de puertos adecuado (`-p 23333:23333`) para que la API sea accesible desde el exterior.
{% endhint %}

***

## Recomendaciones de GPU en Clore.ai

El motor TurboMind de LMDeploy y la cuantización W4A16 ofrecen el mejor rendimiento de su clase — especialmente en GPUs Ampere/Hopper.

| GPU         | VRAM  | Precio en Clore.ai | Rendimiento Llama 3 8B              | Llama 3 70B Q4     |
| ----------- | ----- | ------------------ | ----------------------------------- | ------------------ |
| RTX 3090    | 24 GB | \~$0.12/h          | \~120 tok/s (fp16)                  | ❌ Demasiado grande |
| RTX 4090    | 24 GB | \~$0.70/h          | \~200 tok/s (fp16)                  | ❌ Demasiado grande |
| A100 40GB   | 40 GB | \~$1.20/h          | \~160 tok/s (fp16)                  | \~55 tok/s (W4A16) |
| A100 80GB   | 80 GB | \~$2.00/h          | \~175 tok/s (fp16)                  | \~80 tok/s (fp16)  |
| 2× RTX 4090 | 48 GB | \~$1.40/hr         | \~380 tok/s (paralelismo tensorial) | \~60 tok/s         |

{% hint style="info" %}
**RTX 3090 a \~$0.12/hr** es la mejor opción para modelos 7B–13B. El motor TurboMind de LMDeploy extrae casi el máximo rendimiento de GPUs de consumo. Una sola RTX 3090 sirviendo Llama 3 8B maneja 120 tok/s — suficiente para APIs de producción con 10–20 usuarios concurrentes.

Para modelos 70B: A100 40GB (\~$1.20/hr) con cuantización W4A16 entrega \~55 tok/s — más rentable que dos RTX 4090.
{% endhint %}

***

## Recursos

* 📦 **Docker Hub:** [hub.docker.com/r/openmmlab/lmdeploy](https://hub.docker.com/r/openmmlab/lmdeploy)
* 🐙 **GitHub:** [github.com/InternLM/lmdeploy](https://github.com/InternLM/lmdeploy)
* 📚 **Documentación:** [lmdeploy.readthedocs.io](https://lmdeploy.readthedocs.io)
* 💬 **Discord:** [discord.gg/xa29JuW84p](https://discord.gg/xa29JuW84p)
* 🤗 **Modelos pre-cuantizados:** [huggingface.co/lmdeploy](https://huggingface.co/lmdeploy)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.clore.ai/guides/guides_v2-es/modelos-de-lenguaje/lmdeploy.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.