Token LabBuscar

Empieza aquí: un asistente local de evidencias

Construye tu primer asistente de evidencias: una base local completa

Convierte documentos en un sistema determinista con fuentes. Implementa búsqueda y abstención y establece una referencia antes de incorporar un modelo o agente.

Fuentes y versiones
En este artículo

1. El problema y el compromiso

Imagina a un ingeniero buscando “timeout retry” en un manual. Antes del agente conversacional, devuelve un pasaje público con su ID o abstente si no hay evidencia léxica. El sistema devuelve texto literal: es una base de recuperación, no un LLM, buscador semántico ni servicio seguro de producción.

Entregarás un archivo Python y pruebas separadas. Explicarás el contrato, calcularás una clasificación, reproducirás un fallo y localizarás dónde añadir inferencia. Reserva una o dos sesiones; es una estimación de planificación.

2. Requisitos explicados

Una función transforma entradas; un diccionario nombra campos. Un conjunto elimina repeticiones: repetir palabras no aumenta el peso. El ID es una referencia estable, a diferencia de la posición. Una dataclass congelada evita reasignaciones accidentales, pero no autentica documentos ni impide sustituir la colección.

Una referencia es un comparador sencillo y fijo. Abstenerse significa no superar una regla, no demostrar que no existe respuesta. La traza registra el orden de candidatos. Una respuesta fluida puede ocultar mala recuperación y una puntuación alta puede seleccionar texto irrelevante.

3. Arquitectura y contratos

La colección tiene D1 sobre reintentos, D2 sobre claves y D3 restringido. La CLI llama a answer(), que valida tipo y longitud antes de tokenizar. El filtro público precede a puntuación y trazas para no filtrar IDs privados. Es una política didáctica, no autorización por identidad: no hay login ni tenants.

La salida incluye status, text, source y trace. abstain pone text y source en null. La puntuación no tiene unidades; source es un ID. Los errores generan ValueError. No hay red, persistencia ni efectos laterales. Al añadir HTTP necesitarás autenticación, cuotas, plazos y redacción en esa frontera.

Diseño de referencia: filtrar antes de clasificar y mostrar trazas. Las entradas inválidas fallan; sin coincidencia suficiente se abstiene.
Diseño de referencia: filtrar antes de clasificar y mostrar trazas. Las entradas inválidas fallan; sin coincidencia suficiente se abstiene. Ver diagrama completo

4. Derivar y calcular la puntuación

Q es el conjunto de términos de consulta y D el del documento. La puntuación es cobertura de Q, asimétrica: no penaliza palabras extra. “timeout retry” da 2/2=1 para D1 y 0/2=0 para D2. D3 se elimina, no recibe cero. El umbral 0.5 incluye la igualdad.

“timeout missing” devuelve D1 con 1/2 aunque parte de la consulta no está respaldada. “connection stalled” obtiene cero pese a su relación semántica. Son límites del método. Bajar el umbral aumenta retornos y coincidencias débiles; subirlo no resuelve sinónimos. Cobertura no es confianza ni corrección.

IDQ ∩ Ds(Q,D)
D1timeout, retry2/2 = 1
D2∅0/2 = 0

5. Decisiones y límites

terms() usa minúsculas y letras ASCII y dígitos. No es un tokenizer de modelo ni segmenta chino o japonés, normaliza Unicode o elimina palabras vacías. Las cinco traducciones comparten datos ingleses para reproducir salidas. Un sistema multilingüe requiere análisis y evaluación específicos.

Con N documentos de longitud media L, se analizan N×L caracteres y se ordenan N puntuaciones en O(N log N). Sirve para tres documentos. Precalcula términos y después añade índice invertido, versionado con el texto. Un índice obsoleto puede apuntar a evidencia eliminada. Desempatar por ID estabiliza el resultado.

6. Ampliar después de comprender

BM25 añade frecuencia, rareza y longitud; la búsqueda densa añade similitud de representaciones. Ninguna prueba suficiencia. Al añadir un generador, usa solo texto permitido y conserva IDs estructurados. Las instrucciones documentales son datos no confiables; verifica citas. RAG completo requiere ingesta, actualización, acceso y suficiencia.

No añadas todos los frameworks. Usa la revisión RAG para elegir una mejora, el tutorial SDE para entender la llamada al modelo y SRE cuando necesites acciones con estado. Compara versiones con la misma tarea reservada para no confundir cambios de datos con mejoras.

7. Práctica y verificación

Crea una carpeta y guarda assistant.py y test_assistant.py. Usa Python 3.11 o posterior, sin dependencias, descargas ni claves. No hay aleatoriedad: no se necesita semilla. Ejecuta desde esa carpeta. Se incluye todo el código sin helpers ni datos remotos.

assistant.py

Descargar assistant.py
"""Offline, deterministic retrieval baseline. Python 3.11+, standard library only."""
import json
import re
import sys
from dataclasses import dataclass

@dataclass(frozen=True)
class Document:
    id: str
    text: str
    audience: str = "public"

DOCS = (
    Document("D1", "Retry timeout requests with backoff."),
    Document("D2", "Rotate access keys every month."),
    Document("D3", "Private incident recovery password.", "restricted"),
)

def terms(text):
    return set(re.findall(r"[a-z0-9]+", text.lower()))

def answer(query, docs=DOCS, threshold=0.5):
    if not isinstance(query, str) or len(query) > 2000:
        raise ValueError("query must be a string of at most 2000 characters")
    if not 0 < threshold <= 1:
        raise ValueError("threshold must be in (0, 1]")
    if len({d.id for d in docs}) != len(docs):
        raise ValueError("duplicate document ID")
    q = terms(query)
    candidates = []
    for doc in docs:
        if doc.audience != "public":
            continue  # Filter before ranking or constructing the trace.
        score = len(q & terms(doc.text)) / len(q) if q else 0.0
        candidates.append((score, doc.id, doc.text))
    candidates.sort(key=lambda row: (-row[0], row[1]))
    trace = [{"id": d, "score": s} for s, d, _ in candidates]
    if not candidates or candidates[0][0] < threshold:
        return {"status": "abstain", "text": None, "source": None, "trace": trace}
    _, doc_id, text = candidates[0]
    return {"status": "evidence", "text": text, "source": doc_id, "trace": trace}

if __name__ == "__main__":
    query = " ".join(sys.argv[1:]) or "timeout retry"
    print(json.dumps(answer(query), indent=2))

test_assistant.py

Descargar test_assistant.py
import unittest
from assistant import answer, Document

class ContractTests(unittest.TestCase):
    def test_known(self):
        r = answer("timeout retry")
        self.assertEqual((r["status"], r["source"]), ("evidence", "D1"))
        self.assertEqual(r["trace"][0]["score"], 1.0)
    def test_unknown_and_empty(self):
        for query in ("", "quasar orbit", "日本語"):
            self.assertEqual(answer(query)["status"], "abstain")
    def test_no_private_trace(self):
        r = answer("private incident recovery password")
        self.assertEqual(r["status"], "abstain")
        self.assertNotIn("D3", str(r))
    def test_stable_tie(self):
        docs = (Document("B", "retry"), Document("A", "retry"))
        self.assertEqual(answer("retry", docs)["source"], "A")
    def test_boundaries(self):
        self.assertEqual(answer("timeout missing")["status"], "evidence")
        self.assertEqual(answer("timeout missing extra")["status"], "abstain")
        self.assertEqual(answer("retry", ())["status"], "abstain")
    def test_invalid(self):
        for query in (None, "x" * 2001):
            with self.assertRaises(ValueError): answer(query)
        with self.assertRaises(ValueError): answer("retry", threshold=0)
        with self.assertRaises(ValueError): answer("retry", (Document("A", "x"), Document("A", "y")))
    def test_lexical_failure_is_visible(self):
        # Semantically similar wording is intentionally NOT solved by this baseline.
        self.assertEqual(answer("connection stalled")["status"], "abstain")

if __name__ == "__main__":
    unittest.main()
python3 assistant.py "timeout retry"
python3 assistant.py "quasar orbit"
python3 -m unittest -v test_assistant.py

Resultado: evidence, D1, puntuaciones y ; nunca D3. Las pruebas muestran 7 tests y OK. “quasar orbit” devuelve abstain y valores null. El tiempo de unittest depende del equipo, no es benchmark.

Mantén corpus, consultas y permisos. Cambia solo 0.5 a 0.75; después revierte y precalcula términos. Lo primero cambia conducta; lo segundo debería preservarla. Separa evidencia, retornos insuficientes y abstenciones. Ajusta en desarrollo y reporta en datos intactos: estas pruebas no prueban calidad de despliegue.

Ejercicios originales, no preguntas de empresas

¿Por qué 1 no prueba una respuesta?

Pista: cobertura frente a significado. “do not retry timeout requests” contiene los términos pero niega la acción. El método ignora negación e implicación; añade ese contraejemplo y comprueba respaldo.

¿Por qué filtrar antes de la traza?

Pista: el diagnóstico también sale del sistema. Ocultar texto no basta si se filtran IDs o scores. Filtrar antes los elimina de todos los canales, pero no implementa autorización autenticada.

¿Cómo acelerar sin cambiar respuestas?

Pista: trabajo repetido. Guarda conjuntos por versión inmutable y verifica puntuaciones y desempates idénticos. Invalida al cambiar documento o analizador. Mide después de demostrar equivalencia.

Rúbrica: 1 define; 2 calcula; 3 ejecuta y explica pruebas; 4 añade un fallo y comparación justa; 5 implementa una extensión independiente, conserva contrato y explica límites. No es certificación profesional.

Referencias y siguientes tutoriales

Programa AI/LM: aprender, construir y explicar →
Guía de estudio y esquema de la lecciónOBJETIVOS DE APRENDIZAJE

Comprender → implementar → investigar

Objetivo: explicar el mecanismo, reproducir un ejemplo y comprobar un fallo. Leer no implica dominar.

Predecir, comprobar y conservar evidencia

Antes de revelar la respuesta, predice un resultado. Después registra diferencias y una prueba de transferencia. Se guarda localmente y se comparte entre idiomas.

Abrir cuaderno / exportar / borrar →

El alcance de revisión matemática se registra por lección. No certifica reproducción empírica del artículo; anota posibles errores. Alcance de revisión