Despliegue local de AstaBrief 8B con vLLM para RAG privado

AstaBrief 8B no es un recuperador de información: transforma una pregunta de investigación y fragmentos científicos proporcionados por el sistema en un informe con citas. Esa frontera es la clave para desplegarlo de forma privada. Ejecuta el generador detrás del cortafuegos, mantén el análisis de documentos y las búsquedas en local, y envía al modelo únicamente evidencias ordenadas con IDs de origen estables.

Qué necesita realmente AstaBrief 8B

AstaBrief 8B es un modelo de generación de texto de 8.000 millones de parámetros desarrollado por Ai2, basado en Qwen3-8B y publicado bajo Apache 2.0. La ficha oficial del modelo define como entrada una pregunta de investigación y fragmentos recuperados de literatura científica; no una pregunta que el propio modelo deba buscar por su cuenta. También advierte de que modificar el prompt ajustado durante el fine-tuning o el formato de interacción puede provocar un comportamiento degradado o incoherente.

Para esta guía, utiliza el checkpoint final allenai/AstaBrief_8B. El ejemplo de la ficha del modelo incluye allenai/AstaBrief_8B_SFT, que corresponde al modelo predecesor de ajuste supervisado. Considera esa discrepancia de nombres un detalle de la documentación que conviene verificar frente al checkpoint que descargues, en lugar de asumir sin más que ambos modelos son intercambiables.

El repositorio público Ai2 ScholarQA resulta útil para entender el diseño de referencia: recuperación, reranking opcional, agregación a nivel de artículo, extracción de citas textuales y generación del informe son componentes separados. Una implementación privada debería conservar esa separación aunque sustituya Semantic Scholar por un índice interno.

Una arquitectura local reproducible

Un pipeline privado debería contar con seis etapas explícitas:

1. Ingesta: analiza los PDF, aplica OCR a las páginas escaneadas y conserva el ID del documento, el título, la página, la sección y los offsets de caracteres.
2. Segmentación: divide el texto en pasajes de tamaño moderado sin perder los límites de página ni los encabezados.
3. Recuperación: combina búsquedas léxicas con embeddings cuando importen la terminología, los identificadores o las frases exactas.
4. Reranking: puntúa los candidatos de la primera fase frente a la pregunta completa y conserva un conjunto reducido de evidencias.
5. Ensamblado: asigna IDs de cita inmutables y da formato a los fragmentos según la estructura de referencias que espera AstaBrief.
6. Generación: envía el prompt ensamblado al endpoint local de vLLM.

La decisión de diseño importante no es elegir una base de datos vectorial concreta. Lo esencial es el contrato de evidencia: cada pasaje que se envía al modelo debe llevar un ID estable que la aplicación pueda asociar con un documento y una página.

Mantén estables los IDs de cita

Utiliza IDs como DOC_014_P07_A en lugar de posiciones dentro de un array. Las posiciones cambian cuando se modifican los ajustes de recuperación; un ID basado en documento, página y fragmento sigue siendo auditable.

Guarda la correspondencia fuera del prompt:

{
  "DOC_014_P07_A": {
    "document": "internal_protocol.pdf",
    "page": 7,
    "section": "Methods",
    "char_start": 18420,
    "char_end": 19210
  }
}

En el prompt, muestra el mismo ID junto al fragmento. Después de generar la respuesta, rechaza o marca las citas que no estén en el conjunto de IDs proporcionado. Esto no demuestra que un pasaje respalde cada afirmación, pero evita la forma más básica de fabricación de citas.

Define la profundidad de recuperación antes de ensamblar el contexto

No vuelques en el contexto todos los fragmentos coincidentes. Recupera suficientes resultados para favorecer la cobertura, aplica reranking y empaqueta únicamente los pasajes que quepan en el presupuesto del prompt y respondan directamente a la pregunta. Puedes unir fragmentos adyacentes de la misma página cuando eso conserve un argumento completo, pero mantén IDs separados si el informe final necesita trazabilidad a nivel de página.

El repositorio Ai2 ScholarQA describe una configuración de referencia que recupera 256 candidatos, les aplica reranking y conserva 50 resultados a nivel de artículo. Esos valores pertenecen a ese pipeline público, no son un requisito universal de AstaBrief. Empieza con colecciones privadas más pequeñas, revisa las evidencias que no aparecen y ajusta la recuperación y los límites de contexto a partir de tus propias preguntas.

Sirve AstaBrief 8B con vLLM

La documentación oficial no publica un requisito único de VRAM válido para todas las combinaciones de tipo de datos, longitud de contexto y concurrencia. Empieza con el checkpoint sin cuantizar en un equipo capaz de cargarlo y, antes de evaluar una versión cuantizada, reduce la concurrencia o la longitud de contexto; no des por hecho que la cuantización conserva el comportamiento de las citas sin probarla con tu corpus.

Instala vLLM en un entorno limpio que sea compatible con tu stack de CUDA y PyTorch. Después, inicia el servidor compatible con la API de OpenAI usando el checkpoint final:

pip install -U vllm openai

vllm serve allenai/AstaBrief_8B \
  --host 127.0.0.1 \
  --port 8000 \
  --dtype auto \
  --max-model-len 16000

El valor de --max-model-len es un límite operativo, no una promesa de que cada petición deba contener 16.000 tokens; la ficha del modelo indica un máximo de entrenamiento de 16.000 tokens, mientras que su ejemplo utiliza max_tokens=4096 para la generación.

Verifica el endpoint local

curl http://127.0.0.1:8000/v1/models

Después, haz una llamada utilizando el mismo estilo de prompt que se empleó en los datos de fine-tuning. El ejemplo oficial usa una temperatura de 0.7, un top-p de 0.95, un máximo de 4.096 tokens generados y el token EOS del tokenizador como condición de parada.

from openai import OpenAI

client = OpenAI(
    base_url="http://127.0.0.1:8000/v1",
    api_key="local-only",
)

response = client.chat.completions.create(
    model="allenai/AstaBrief_8B",
    temperature=0.7,
    top_p=0.95,
    max_tokens=4096,
    messages=[
        {"role": "user", "content": assembled_prompt},
    ],
)

print(response.choices[0].message.content)

En un servidor privado, vincula el servicio a loopback o a una interfaz interna, coloca la autenticación y TLS en tu gateway y bloquea el acceso público. Un modelo local no convierte automáticamente en privados los logs, los archivos PDF temporales o las trazas.

Construye la petición de recuperación privada

El siguiente esqueleto deja deliberadamente abierta la implementación del índice. Lo importante es la lista de evidencias ordenadas, los IDs inmutables y el límite que define el prompt.

from dataclasses import dataclass
from openai import OpenAI

@dataclass
class Evidence:
    ref_id: str
    text: str
    title: str
    page: int


def build_prompt(question: str, evidence: list[Evidence]) -> str:
    references = "\n\n".join(
        f"[{item.ref_id}] {item.title} (page {item.page})\n{item.text}"
        for item in evidence
    )
    return f"""Research question:
{question}

Retrieved references:
{references}

Write a cited research report answering the question. Use only the supplied
references for factual support. Attach the supplied reference IDs to claims.
If the references do not establish a point, say that the evidence is
insufficient instead of inventing a source.
"""


def answer(question: str, evidence: list[Evidence]) -> str:
    client = OpenAI(base_url="http://127.0.0.1:8000/v1", api_key="local-only")
    prompt = build_prompt(question, evidence)
    result = client.chat.completions.create(
        model="allenai/AstaBrief_8B",
        temperature=0.7,
        top_p=0.95,
        max_tokens=4096,
        messages=[{"role": "user", "content": prompt}],
    )
    return result.choices[0].message.content

En producción, utiliza la plantilla de prompt oficial de AstaBrief e inserta en ella los fragmentos recuperados conservando sus IDs de referencia. La instrucción abreviada anterior muestra cómo integrar vLLM, pero no sustituye al formato utilizado durante el fine-tuning.

Tu índice privado puede utilizar BM25, recuperación densa o un enfoque híbrido. Conserva los metadatos durante todas las etapas. Un pasaje sin el ID de documento y el número de página no basta para elaborar un informe de investigación defendible, aunque la prosa generada parezca correcta.

Añade controles de citas y privacidad antes de pasar a producción

Los resultados publicados de AstaBrief en ScholarQA-CS2 sirven como contexto, no como garantía para tu corpus. En el conjunto de prueba de 100 preguntas de la ficha del modelo, AstaBrief 8B registra una precisión de citas de 90.5 y una cobertura de citas de 78.2; la precisión de las respuestas es de 89.0. Que la cobertura de citas sea inferior a su precisión deja una advertencia práctica: un informe puede citar correctamente el material proporcionado y, aun así, omitir evidencias relevantes.

Utiliza un control con cuatro comprobaciones:

1. Validez de las referencias: cada ID de cita generado existe en la lista permitida de la petición.
2. Resolución de metadatos: cada ID apunta a un documento, una página y un fragmento de texto almacenado.
3. Respaldo de la evidencia: un revisor o un verificador independiente comprueba si el pasaje respalda realmente la afirmación cercana.
4. Recall de recuperación: mantén un conjunto pequeño de preguntas etiquetadas con los documentos y páginas esperados, y mide los fallos después de cambiar la segmentación, los embeddings o el reranking.

Mantén el servidor del modelo, el índice, el almacenamiento de objetos, los logs y la monitorización dentro del mismo perímetro de confianza, salvo que tu política permita explícitamente un servicio externo. Desactiva el registro del cuerpo de las peticiones para documentos sensibles, anonimiza las consultas en las trazas cuando sea posible y define la retención de los PDF subidos y de los informes generados.

No reutilices como benchmark local la cifra de 51.1 segundos del modo Fast publicada por Ai2. Ese dato describe el pipeline Asta completo de extremo a extremo, mientras que un despliegue autoalojado cambia la GPU, el sistema de recuperación, el batching, la longitud del prompt y la ruta de red. Mide por separado la recuperación, el reranking, el tiempo hasta el primer token, el tiempo de generación y el tiempo total de cada petición.

Soluciona los problemas por capas

Este diagnóstico por capas evita confundir un fallo de recuperación con un problema del modelo y también impide que un desajuste en el formato del prompt se “solucione” añadiendo más documentos.

Utiliza AstaBrief 8B si buscas un generador local especializado en informes y estás dispuesto a hacerte cargo de la calidad de la recuperación, la correspondencia de las fuentes y la validación. vLLM resuelve el servicio del modelo; no proporciona búsquedas documentales, trazabilidad de citas ni controles de privacidad.

Fuentes

• Ficha del modelo AstaBrief 8B
• Documentación del servidor compatible con OpenAI de vLLM
• Plantilla de prompt de AstaBrief
• Biblioteca Ai2 ScholarQA
• Anuncio de Ai2 sobre AstaBrief