> For the complete documentation index, see [llms.txt](https://docs.clore.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.clore.ai/guides/guides_v2-es/modelos-de-lenguaje/lmdeploy.md).

# LMDeploy

**Kit de implementación eficiente de LLM de Shanghai AI Lab** — inferencia, cuantización y servicio de nivel de producción para modelos de lenguaje grandes con batching continuo y PagedAttention.

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

***

## ¿Qué es LMDeploy?

LMDeploy es un conjunto de herramientas integral para comprimir, implementar y servir modelos de lenguaje grandes en producción. Creado por el mismo equipo detrás de OpenMMLab (MMDetection, MMSeg), lleva optimizaciones de nivel de investigación a la implementación práctica:

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

En comparación con vLLM, el motor TurboMind de LMDeploy ofrece \~1,36× más rendimiento en Llama 3 8B con batch=32, y su cuantización AWQ es de primera clase — no una idea de último momento. Para VLM (especialmente InternVL2), LMDeploy es la pila de implementación de referencia.

### ¿Por qué LMDeploy?

| Función                         | LMDeploy | vLLM     | TGI      |
| ------------------------------- | -------- | -------- | -------- |
| Agrupación continua             | ✅        | ✅        | ✅        |
| 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: Selecciona un servidor GPU

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

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

### Paso 2: Despliega el Docker de LMDeploy

```
Imagen de 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=your_hf_token_here  # Para modelos con acceso restringido
```

### Paso 3: Conéctate por SSH y verifica

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

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

***

## Iniciando el servidor API

### Servidor compatible con OpenAI (recomendado)

```bash
# Sirve 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 del 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 (compatibilidad más amplia)

```bash
# Usa el motor PyTorch para modelos no compatibles con 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 de la API: http://0.0.0.0:23333/docs
```

{% hint style="success" %}
Una vez iniciado, LMDeploy expone documentación interactiva de la API en `http://<your-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

La AWQ de LMDeploy (cuantización de pesos con conciencia de activación) produce una calidad excelente a 4 bits:

```bash
# Cuantiza un modelo a AWQ de 4 bits
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

# Sirve 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 |
| ----------------------- | --------- | ------------------ | ----------------------- |
| Sin cuantización (bf16) | \~14 GB   | Ninguno            | Base                    |
| SmoothQuant W8A8        | \~8 GB    | Mínima             | +20%                    |
| AWQ W4A16               | \~4 GB    | Baja               | +15%                    |
| GPTQ W4A16              | \~4 GB    | Baja               | +10%                    |

{% hint style="info" %}
**Recomendación de AWQ:** Para la mayoría de los casos de uso, AWQ de 4 bits es el mejor equilibrio entre calidad y ahorro de VRAM. Usa `--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://<clore-node-ip>:<api-port>/v1",
    api_key="none"
)

# Finalización 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)
```

### Transmisión

```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 nativo de Python 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)
```

***

## Implementación con varias GPU

### Paralelismo tensorial

```bash
# Distribuye un modelo de 70B entre 4 GPU
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,  # Proporción de caché KV (0.0-1.0)
    quant_policy=0,             # 0=sin cuantización, 4=caché KV de 4 bits, 8=caché KV de 8 bits
    rope_scaling_factor=1.0,    # Para contexto ampliado
    num_tokens_per_iter=4096,   # Tamaño del bloque 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)
```

***

## Monitorización y métricas

### Comprobar estado del servidor

```bash
# Endpoint de comprobación de salud
curl http://localhost:23333/health

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

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

### Monitorización 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 de 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:
```

***

## Evaluación comparativa

```bash
# Herramienta de benchmark integrada
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 de 80 GB, espera \~2,2× más rendimiento que en RTX 4090 con alta concurrencia debido al ancho de banda de memoria HBM2e (2 TB/s frente a 1 TB/s).

***

## Recomendaciones de GPU para Clore.ai

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

| Caso de uso                           | GPU           | VRAM  | Por qué                                                              |
| ------------------------------------- | ------------- | ----- | -------------------------------------------------------------------- |
| Modelos de 7–13B, desarrollo/staging  | **RTX 3090**  | 24 GB | Mejor relación precio/VRAM; gestiona 7B bf16 o 13B AWQ               |
| Modelos de 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 de 70B, servicio para equipos | **A100 40GB** | 40 GB | Cabe 70B AWQ; memoria ECC para mayor fiabilidad                      |
| Modelos de 70B, alto rendimiento      | **A100 80GB** | 80 GB | Cabe 70B bf16; 2× de rendimiento frente a A100 40 GB con batch=32    |

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

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

**Opción para producción:** A100 80GB — ejecuta Qwen2-72B o Llama 3 70B en bf16 completo sin compensaciones en la calidad por cuantización; encaja fácilmente en servicio GPU con múltiples instancias.

***

## Solución de problemas

### El modelo no se carga

```bash
# Comprueba que el token de HuggingFace esté configurado
echo $HUGGING_FACE_HUB_TOKEN

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

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

### Memoria insuficiente en CUDA

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

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

### Puerto ya en uso

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

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

{% hint style="warning" %}
**Modo de red de Docker:** Al ejecutar en Docker, asegúrate de que el contenedor use `--network host` o una asignación de puertos adecuada (`-p 23333:23333`) para que la API sea accesible desde fuera.
{% endhint %}

***

## Recomendaciones de GPU para Clore.ai

El motor TurboMind de LMDeploy y la cuantización W4A16 ofrecen un rendimiento de primera clase — especialmente en GPU Ampere/Hopper.

| GPU         | VRAM  | Precio de Clore.ai                        | Rendimiento de Llama 3 8B           | Llama 3 70B Q4     |
| ----------- | ----- | ----------------------------------------- | ----------------------------------- | ------------------ |
| RTX 3090    | 24 GB | $0.07–0.21/h                              | \~120 tok/s (fp16)                  | ❌ Demasiado grande |
| RTX 4090    | 24 GB | $0.14–0.42/h                              | \~200 tok/s (fp16)                  | ❌ Demasiado grande |
| A100 40GB   | 40 GB | [bare metal](https://clore.ai/bare-metal) | \~160 tok/s (fp16)                  | \~55 tok/s (W4A16) |
| A100 80GB   | 80 GB | [bare metal](https://clore.ai/bare-metal) | \~175 tok/s (fp16)                  | \~80 tok/s (fp16)  |
| 2× RTX 4090 | 48 GB | $0.28–0.84/h                              | \~380 tok/s (paralelismo tensorial) | \~60 tok/s         |

{% hint style="info" %}
**RTX 3090 a $0.07–0.21/h** es la mejor opción para modelos de 7B–13B. El motor TurboMind de LMDeploy extrae un rendimiento casi máximo de las GPU 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 de 70B: A100 40GB ([bare metal](https://clore.ai/bare-metal)) con cuantización W4A16 ofrece \~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 precuantizados:** [huggingface.co/lmdeploy](https://huggingface.co/lmdeploy)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.