Cómo conectar tokens de cuenta de Hugging Face y endpoints de inferencia personalizados a HuggingChat

Para ejecutar modelos de código abierto privados o adaptaciones propietarias ajustadas (fine-tuning) dentro de la interfaz de HuggingChat, es fundamental comprender primero su arquitectura técnica. Muchos desarrolladores exploran la interfaz pública de HuggingChat (hf.co/chat) buscando un panel de configuración donde ingresar la URL de su endpoint privado y un token de API personal. Sin embargo, la versión pública de HuggingChat funciona como un servicio multiinquilino alojado y gestionado directamente sobre los enrutadores comunitarios de Hugging Face; por motivos de aislamiento e infraestructura, no permite que los usuarios conecten endpoints privados externos a la interfaz compartida.

La vía oficial y lista para entornos de producción para interactuar con modelos privados utilizando la experiencia de HuggingChat es desplegar una instancia propia de Chat UI, la aplicación web de código abierto desarrollada en SvelteKit que impulsa HuggingChat. Chat UI es compatible de forma nativa con la especificación de API de OpenAI, lo que permite conectar el cliente web directamente con un endpoint dedicado de Hugging Face Inference Endpoints mediante las variables de entorno OPENAI_BASE_URL y OPENAI_API_KEY. Esta solución puede implementarse en minutos a través de un Hugging Face Space privado o en servidores locales mediante Docker.

Flujo de arquitectura

La integración completa se compone de tres módulos principales:

1. Hugging Face Inference Endpoints: Aloja los pesos de su modelo privado o personalizado (como Llama 3.3, Mistral, Qwen o adaptadores LoRA propios) sobre contenedores optimizados como Text Generation Inference (TGI) o vLLM, exponiendo una ruta REST compatible con OpenAI (/v1/chat/completions).
2. User Access Token (HF_TOKEN): Proporciona la autenticación segura para autorizar las solicitudes dirigidas a su endpoint privado.
3. Chat UI (Instancia privada de HuggingChat): La interfaz gráfica que consume el endpoint, ofreciendo la experiencia completa de conversación, soporte multimodal y control de herramientas.

+-------------------------------------------------------------+
|                Instancia privada de Chat UI                 |
|             (Hugging Face Space / Docker local)             |
+-------------------------------------------------------------+
                               |
               OPENAI_BASE_URL | OPENAI_API_KEY (hf_xxx)
                               v
+-------------------------------------------------------------+
|             Hugging Face Inference Endpoint                 |
|   https://<endpoint-id>.<region>.<cloud>.endpoints.huggingface.cloud/v1   |
|                 (Motor TGI / vLLM en GPU)                   |
+-------------------------------------------------------------+
                               |
                               v
+-------------------------------------------------------------+
|               Pesos privados / Repositorio Hub              |
+-------------------------------------------------------------+

Paso 1: Desplegar el modelo personalizado en Inference Endpoints

Para servir un modelo privado en infraestructura dedicada de Hugging Face:

1. Ingrese a la consola de Inference Endpoints.
2. Haga clic en Create New Endpoint.
3. Model Repository: Escriba el identificador de su repositorio privado (por ejemplo, su-organizacion/modelo-privado-8b) o seleccione un modelo de acceso público.
4. Cloud Provider & Region: Seleccione su proveedor cloud preferido (AWS o Azure) y una región geográfica próxima a sus usuarios.
5. Instance Type: Asigne el hardware de GPU correspondiente según el tamaño de los parámetros (por ejemplo, 1x NVIDIA A10G para modelos de 8B, o múltiples A100/H100 para modelos de 70B).
6. Framework & Engine: Compruebe que el contenedor utilice Text Generation Inference (TGI) o vLLM. Ambos motores ofrecen endpoints compatibles con OpenAI por defecto.
7. Haga clic en Create Endpoint.

Espere a que el estado cambie de Building a Running. Copie y guarde la URL única generada en el panel de control:

https://<endpoint-id>.<region>.<cloud>.endpoints.huggingface.cloud

Paso 2: Generar un token de acceso a la cuenta

El endpoint dedicado exige credenciales de autorización en cada llamada de inferencia:

1. Vaya a Settings > Access Tokens en su perfil (hf.co/settings/tokens).
2. Haga clic en Create new token.
3. Configure el tipo de token:
   • Fine-grained token (Recomendado): En la sección Inference, active el permiso "Make calls to your Inference Endpoints".
   • Read token: Un token con alcance Read estándar también permite autenticar peticiones contra endpoints bajo su titularidad personal.
4. Copie la clave generada (hf_...) y guárdela de forma segura.

Paso 3: Conectar el endpoint a Chat UI (HuggingChat)

Chat UI detecta los modelos compatibles añadiendo automáticamente /v1 a la URL base.

Opción A: Despliegue con un clic en Hugging Face Spaces (Recomendado)

Si desea habilitar un entorno de chat privado para su equipo sin gestionar servidores físicos:

1. Abra la plantilla oficial de Space de Chat UI.
2. Configure la visibilidad del Space como Private para bloquear el acceso público.
3. En la pestaña Settings > Variables and Secrets del Space, cree las siguientes variables de entorno:
   • OPENAI_BASE_URL: https://<endpoint-id>.<region>.<cloud>.endpoints.huggingface.cloud/v1
   • OPENAI_API_KEY: hf_************************ (el token de acceso generado en el Paso 2)
4. (Opcional) Defina MONGODB_URL si requiere persistencia multiusuario de historiales tras reinicios del Space. Para pruebas individuales, Chat UI utiliza automáticamente una base de datos local integrada.
5. Reinicie el Space. Chat UI consultará la ruta /v1/models de su endpoint y el modelo quedará inmediatamente disponible en la interfaz.

Opción B: Despliegue local o autogestionado (Node.js / Docker)

Para ejecutar la interfaz en su estación de trabajo o en un clúster interno:

1. Clone el repositorio de Chat UI:

   git clone https://github.com/huggingface/chat-ui.git
   cd chat-ui
   

2. Cree un archivo de configuración .env.local:

   # Configuración del endpoint de inferencia
   OPENAI_BASE_URL=https://<endpoint-id>.<region>.<cloud>.endpoints.huggingface.cloud/v1
   OPENAI_API_KEY=hf_su_token_aqui
   
   # Base de datos (opcional para desarrollo local; se almacena en ./db por defecto)
   # MONGODB_URL=mongodb://localhost:27017
   

3. Si su endpoint personalizado no expone la ruta de descubrimiento /v1/models o si desea personalizar el nombre de visualización y los límites de generación, defina la variable JSON5 MODELS en .env.local:

   MODELS=`[
     {
       "id": "tgi",
       "name": "Modelo Privado Corporativo",
       "multimodal": false,
       "supportsTools": false,
       "parameters": {
         "temperature": 0.7,
         "max_tokens": 4096
       }
     }
   ]`
   

4. Instale las dependencias e inicie el servidor de desarrollo:

   npm install
   npm run dev -- --open
   

La aplicación se iniciará en http://localhost:5173, ofreciendo la experiencia completa de HuggingChat comunicándose directamente con sus pesos privados.

Verificación previa mediante terminal

Antes de interactuar desde el navegador, compruebe la conectividad mediante curl para descartar problemas de red o de autenticación:

curl -X POST "https://<endpoint-id>.<region>.<cloud>.endpoints.huggingface.cloud/v1/chat/completions" \
  -H "Authorization: Bearer hf_su_token_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tgi",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Hello! Confirm endpoint readiness."}
    ],
    "max_tokens": 50
  }'

Si recibe una respuesta JSON con el texto generado por el modelo, el contenedor y las credenciales están operativos.

Consideraciones prácticas y recomendaciones

• Diferencia entre Assistants públicos y despliegues dedicados: Crear un "Assistant" en la versión pública hf.co/chat permite personalizar instrucciones del sistema y subir documentos para RAG, pero el modelo base sigue siendo uno de los modelos públicos compartidos. Si sus requerimientos exigen privacidad absoluta de pesos y datos, alojar Chat UI sobre un Inference Endpoint privado es la única alternativa.
• Arranque en frío (Scale-to-Zero): Si su endpoint tiene activado el escalado a cero réplicas para reducir costos cuando no hay actividad, la primera solicitud enviada desde la interfaz puede experimentar un tiempo de espera prolongado mientras se inicializa el contenedor GPU. En entornos de trabajo productivos, se recomienda mantener al menos 1 réplica activa.
• Transmisión de respuestas (Streaming): Chat UI utiliza Server-Sent Events (SSE) para renderizar texto en tiempo real. TGI y vLLM soportan streaming de manera nativa; si utiliza un proxy inverso (como Nginx), asegúrese de desactivar el búfer de proxy (proxy_buffering off;).

Referencias

• Chat UI · Hugging Face
• Configuration Overview · Hugging Face
• Running Locally · Hugging Face
• Inference Endpoints · Hugging Face