La hoja de propiedades de un componente de IA

Descripción

El módulo te dio, pieza por pieza, todo lo que hay que saber para ubicar un componente de IA: su contrato es probabilístico (L2), vive tras una frontera y propone (L3), arrastra cinco propiedades de golpe (L4), es un núcleo dentro de una cáscara (L5), y su cáscara se dimensiona por su tolerancia (L6). Esta lección junta todo eso en un solo artefacto reutilizable: la hoja de propiedades de un componente de IA. Es una ficha con los mismos campos para cualquier feature —ubicación, tolerancia, presupuesto de latencia y costo, compuerta de eval, guardrail, fallback, cáscara determinista, lazo de datos—, y cada campo apunta al módulo de la guía que lo trabaja a fondo. Llenar esta hoja es el acto de arquitectar una feature de IA, y es lo que harás en el proyecto (L8) y, ampliado, en el capstone de toda la guía (M8).

Vas a ver, ejecutada, la hoja de la búsqueda semántica de Mercado: los diez campos llenos, cada uno etiquetado con su módulo. Y vas a ver por qué esta hoja es, a la vez, el resumen del módulo y el índice del resto de la guía —porque los módulos 2 al 7 son, uno por uno, cómo llenar bien cada campo—.

Conexión con el módulo. Esta es la lección de consolidación. No introduce una idea nueva; le da forma de artefacto a todas las del módulo, para que salgas con algo que puedes usar mañana en tu trabajo. La hoja toma la ubicación y la tolerancia (este módulo), y deja como campos-por-completar el presupuesto (M2), el eval (M3), el guardrail (M4), el fallback (M5), la cáscara a fondo (M6) y el lazo de datos (M7). La lección 8 llena una hoja de punta a punta para una feature real; el módulo 8 hace lo mismo pero construyendo cada mecanismo. La frontera con AI Engineering, una vez más: la hoja describe las propiedades arquitectónicas del componente —dónde vive, qué lo contiene—, nunca su construcción interna (el prompt, el RAG, el fine-tuning), que es el trabajo de AI Eng al que la hoja simplemente hace sitio.

Una analogía: la ficha técnica de un componente eléctrico

Un ingeniero que diseña un circuito no "conecta un motor y ya". Antes de poner cualquier componente, consulta su ficha técnica (datasheet): el documento estandarizado que dice todo lo que necesita saber para ubicarlo bien —voltaje de operación, corriente máxima, disipación de calor, tolerancia, rango de temperatura, qué protecciones necesita alrededor—. La ficha no le dice cómo se fabricó el motor por dentro (eso es asunto del fabricante); le dice sus propiedades de integración: qué necesita para funcionar sin quemar el resto del circuito.

Lo poderoso de la ficha técnica es que es el mismo formato para todos los componentes. Un motor, un capacitor y un microcontrolador tienen fichas con campos comparables, aunque sean cosas distintas. Eso deja al ingeniero razonar de forma uniforme: "¿cuál es el voltaje de este?, ¿qué protección necesita?", sin reinventar el análisis para cada pieza. La ficha es lo que convierte "meter un componente" de una improvisación a un procedimiento.

Aquí está el punto: la hoja de propiedades es la ficha técnica de un componente de IA. No describe cómo se construyó el modelo por dentro (eso es AI Engineering, el "fabricante"); describe sus propiedades de integración —dónde vive, cuánta latencia y costo tolera el sistema, qué lo valida, qué pasa si se cae, qué lo contiene—. Y es el mismo formato para cualquier feature de IA de Mercado: la búsqueda, el agente, las recomendaciones, el generador. Igual que el ingeniero eléctrico, llenar la ficha es lo que convierte "agregar IA" de una improvisación a un procedimiento. Esta lección te da la ficha; la guía entera te enseña a llenar cada campo bien.

Ejemplo trabajado: la hoja de la búsqueda semántica de Mercado

Vamos a modelar la hoja como una estructura de datos —una dataclass— y a imprimirla, con cada campo etiquetado con el módulo de la guía que lo desarrolla. Usamos la búsqueda semántica, una feature tolerante, justo para mostrar que incluso una feature de cáscara delgada tiene su ficha completa: los campos existen todos, aunque algunos se llenen "ligero".

# Lección 7: la hoja de propiedades de un componente de IA.
# Consolidación: TODO componente de IA se describe con los mismos campos,
# y cada campo apunta al módulo de la guía que lo trabaja a fondo.
from dataclasses import dataclass, asdict


@dataclass
class AIComponentSheet:
    name: str
    location: str          # dónde vive en el sistema
    nd_tolerance: int      # 3 (nada) .. 15 (mucha)
    latency_budget_ms: int # M2
    cost_budget_usd: float # M2
    eval_gate: str         # M3
    guardrail: str         # M4
    fallback: str          # M5
    deterministic_shell: str  # M6
    feedback_loop: str     # M7


# La hoja de la búsqueda semántica de Mercado: una feature TOLERANTE.
# (No construimos el RAG: eso es AI Engineering. Solo sus propiedades.)
sheet = AIComponentSheet(
    name="semantic_search",
    location="detras de search-service, tras la ruta clasica por keyword",
    nd_tolerance=13,
    latency_budget_ms=400,
    cost_budget_usd=0.0008,
    eval_gate="recall@10 sobre 50 consultas etiquetadas; baja el score -> bloquea deploy",
    guardrail="filtrar resultados sin permiso del usuario; ocultar productos retirados",
    fallback="si el modelo tarda/cae -> busqueda clasica por keyword",
    deterministic_shell="delgada: re-rankea, nunca decide precio ni stock",
    feedback_loop="clicks y compras post-busqueda alimentan el eval-set",
)

MODULE_OF = {
    "location": "M1", "nd_tolerance": "M1",
    "latency_budget_ms": "M2", "cost_budget_usd": "M2",
    "eval_gate": "M3", "guardrail": "M4", "fallback": "M5",
    "deterministic_shell": "M6", "feedback_loop": "M7",
}

print(f"=== Hoja de propiedades: {sheet.name} ===")
for field, value in asdict(sheet).items():
    if field == "name":
        continue
    mod = MODULE_OF.get(field, "  ")
    print(f"  [{mod:>2}] {field:<20} {value}")

print()
print("Cada [Mx] es el modulo que profundiza ese campo. La hoja es el")
print("contrato arquitectonico del componente: se llena aqui (M1) y se")
print("completa a lo largo de la guia.")

Qué esperar. Al correr el archivo, la salida es exactamente esta:

=== Hoja de propiedades: semantic_search ===
  [M1] location             detras de search-service, tras la ruta clasica por keyword
  [M1] nd_tolerance         13
  [M2] latency_budget_ms    400
  [M2] cost_budget_usd      0.0008
  [M3] eval_gate            recall@10 sobre 50 consultas etiquetadas; baja el score -> bloquea deploy
  [M4] guardrail            filtrar resultados sin permiso del usuario; ocultar productos retirados
  [M5] fallback             si el modelo tarda/cae -> busqueda clasica por keyword
  [M6] deterministic_shell  delgada: re-rankea, nunca decide precio ni stock
  [M7] feedback_loop        clicks y compras post-busqueda alimentan el eval-set

Cada [Mx] es el modulo que profundiza ese campo. La hoja es el
contrato arquitectonico del componente: se llena aqui (M1) y se
completa a lo largo de la guia.

Lee la hoja de arriba abajo, porque cada línea es una decisión arquitectónica que este módulo te enseñó a ver y los siguientes te enseñarán a resolver bien.

Los dos primeros campos —location y nd_tolerance— son de este módulo. La ubicación ("detrás de search-service, tras la ruta clásica por keyword") dice dónde vive el componente y qué lo rodea: la búsqueda semántica no reemplaza la búsqueda clásica, se pone detrás de ella, lo que ya insinúa el fallback. La tolerancia (13) resume el análisis de la lección 6: una feature tolerante, de cáscara delgada. Estos dos campos son lo que sabes hacer al terminar M1.

Los demás campos son el mapa del resto de la guía. El presupuesto (400 ms, $0.0008 por llamada) es el módulo 2: cuánta latencia y costo puede absorber el sistema. La compuerta de eval (recall@10 sobre 50 consultas, que bloquea el deploy si baja) es el módulo 3: cómo se prueba algo probabilístico. El guardrail (filtrar sin permiso, ocultar retirados) es el módulo 4: qué se valida en la frontera. El fallback (a la búsqueda clásica si el modelo cae) es el módulo 5: qué pasa cuando falla. La cáscara determinista ("delgada: re-rankea, nunca decide precio ni stock") es el módulo 6: la contención, aquí explícitamente ligera porque la feature es tolerante. Y el lazo de datos (clicks y compras alimentan el eval-set) es el módulo 7: cómo mejora con el uso.

Fíjate en lo que la hoja no tiene: no hay un campo "prompt", ni "modelo de embeddings", ni "cómo se hace el RAG". Eso es deliberado —es la frontera con AI Engineering—. La hoja describe cómo el componente se integra y se contiene, no cómo se construye por dentro. El "fabricante del motor" (AI Eng) se encarga de que el núcleo funcione; la hoja se encarga de ubicarlo bien en el circuito.

Y el cierre lo dice: la hoja es el contrato arquitectónico del componente. Se empieza a llenar aquí (M1, los dos primeros campos) y se completa a lo largo de la guía. Cuando termines los ocho módulos, sabrás llenar las diez líneas para cualquier feature de IA que un sistema quiera añadir. La guía entera cabe en esta ficha.

Profundización: la hoja como índice, contrato y checklist

Vale la pena ver los tres usos de la hoja, porque cada uno la vuelve valiosa en un momento distinto del trabajo.

La hoja es el índice de la guía. Mira la columna de módulos: [M1] [M1] [M2] [M2] [M3] [M4] [M5] [M6] [M7]. No es coincidencia que aparezcan casi todos: la hoja es la guía, vista como una sola ficha. Aprender arquitectura AI-native es aprender a llenar cada campo bien, y cada módulo es un campo. Esto te da un mapa mental para el resto del curso: cuando entres al módulo 2, sabrás que estás aprendiendo a llenar latency_budget_ms y cost_budget_usd; en el 4, guardrail; y así. La hoja convierte una lista de temas en una estructura con propósito.

Campo de la hoja           Pregunta que responde                     Módulo
─────────────────────────  ────────────────────────────────────────  ──────
location                   ¿Dónde vive y qué lo rodea?               M1
nd_tolerance               ¿Cuánta no-determinación aguanta?         M1
latency_budget_ms          ¿Cuánto puede tardar?                     M2
cost_budget_usd            ¿Cuánto puede costar por llamada?         M2
eval_gate                  ¿Cómo pruebo algo probabilístico?         M3
guardrail                  ¿Qué valido en la frontera?               M4
fallback                   ¿Qué pasa si el modelo falla?             M5
deterministic_shell        ¿Qué contiene sus acciones?               M6
feedback_loop              ¿Cómo mejora con el uso?                  M7

La hoja es un contrato entre equipos. Cuando el equipo de AI Engineering entrega un componente (un buscador semántico, un agente), la hoja es el documento que dice cómo el equipo de plataforma lo va a integrar y contener. Deja explícito qué garantiza la cáscara, cuál es el presupuesto, qué pasa si el núcleo falla. Es la interfaz entre "quién construye el núcleo" y "quién lo ubica en el sistema" —dos trabajos distintos, con la hoja como frontera limpia entre ellos—. Sin la hoja, esa frontera se difumina y los dos equipos terminan pisándose (AI Eng metiéndose en cómo se integra, plataforma metiéndose en cómo se prompt-ea).

La hoja es un checklist de completitud. Un campo vacío en la hoja es un frente sin resolver —justo los que la lección 4 llamó "el iceberg"—. Si vas a lanzar una feature y su hoja tiene fallback en blanco, sabes que no tiene plan para cuando el modelo se caiga; si tiene guardrail vacío en una feature que publica contenido, sabes que su salida no está validada. La hoja convierte "¿estamos listos para producción?" de una sensación a una revisión concreta: ¿están los diez campos llenos, y llenos a la altura de la tolerancia de la feature? Una feature tolerante puede tener campos "ligeros" (la búsqueda tiene una cáscara "delgada"), pero ninguno vacío —tolerante no es lo mismo que descuidado—.

Una hoja por feature, no una por sistema. Cada componente de IA tiene su propia hoja, porque cada uno tiene su tolerancia y su perfil de riesgo (lección 6). Mercado con sus cuatro features tendrá cuatro hojas: la de la búsqueda (delgada), la del agente de reembolsos (todos los campos "gruesos"), la de recomendaciones y la del generador (intermedias, con distinto énfasis). Comparar las cuatro hojas lado a lado es, de un vistazo, el mapa de dónde está la mayor superficie de riesgo de IA del sistema —y por lo tanto dónde invertir más ingeniería de contención—.

Errores comunes

Dejar campos en blanco y llamar a la feature "lista". Qué pasa: el equipo llena location, eval_gate y poco más, deja fallback, guardrail y deterministic_shell vacíos, y declara la feature lista para producción. Los campos vacíos son exactamente los frentes del iceberg que van a explotar. Por qué pasa: los campos vacíos no duelen hasta que el modelo se cae, o alucina, o alguien inyecta. Cómo detectarlo: tu hoja tiene campos sin llenar y no hay una justificación explícita de por qué esa feature no los necesita. Cómo corregirlo: exige que los diez campos tengan algo —aunque sea "no aplica porque no toca estado" con la razón—. Un campo en blanco es un frente sin decidir; un campo con "no aplica y esta es la razón" es una decisión tomada. La diferencia entre las dos es la diferencia entre una feature diseñada y una improvisada.

Meter la construcción del núcleo en la hoja. Qué pasa: alguien agrega a la hoja campos como "prompt", "modelo de embeddings", "estrategia de chunking del RAG", y la hoja se convierte en la documentación de cómo se construyó el modelo. Por qué pasa: se confunde describir el componente con describir su interior. Cómo detectarlo: tu hoja tiene campos que responden "¿cómo funciona el núcleo por dentro?" en vez de "¿cómo se integra y se contiene?". Cómo corregirlo: mantén la hoja en la capa de integración —las propiedades de la ficha técnica, no los planos de fabricación—. El prompt y el RAG son asunto de AI Engineering y viven en su documentación; la hoja arquitectónica hace sitio a ese núcleo (lo trata como una caja que propone) sin absorber su construcción. Si la hoja empieza a hablar de tokens de un prompt, cruzaste la frontera.

Una sola hoja para todo el sistema. Qué pasa: el equipo hace una única hoja "de la IA de Mercado" que promedia las cuatro features. El resultado es inútil: mezcla la tolerancia 13 de la búsqueda con la tolerancia 3 del agente, y termina con una cáscara "promedio" que sobre-diseña la búsqueda y sub-diseña el agente. Por qué pasa: una sola hoja parece más simple de mantener. Cómo detectarlo: tienes una hoja con campos que dicen "depende de la feature" o valores promediados. Cómo corregirlo: una hoja por componente de IA. La tolerancia y el perfil de riesgo son por feature (lección 6), así que la hoja también. Cuatro features, cuatro hojas. Compararlas es información valiosa; fusionarlas la destruye.

Ejercicios

Ejercicio 1 — Llena la hoja del agente de reembolsos. El agente de soporte que ejecuta reembolsos es la feature más intolerante de Mercado (tolerancia 3, todos los mecanismos obligatorios). Escribe su hoja de propiedades —los diez campos—, y contrasta cada campo con el de la búsqueda semántica para mostrar por qué su cáscara es "gruesa" donde la de la búsqueda es "delgada".

name                 support_agent_refunds
location             en support-service, entre el ticket del cliente y la API de pagos
nd_tolerance         3   (vs 13 de la busqueda: intolerante, toca dinero)
latency_budget_ms    5000  (mas holgado: el cliente espera una resolucion, no una busqueda instantanea)
cost_budget_usd      0.02  (mas alto: razona sobre el ticket; se justifica por el valor de resolver)
eval_gate            % de propuestas dentro de politica sobre 100 tickets etiquetados; baja -> bloquea deploy
guardrail            validar entrada (prompt injection en el ticket) Y salida (schema {order_id, amount})
fallback             si el modelo cae -> encolar el ticket a un agente humano (nunca auto-aprobar)
deterministic_shell  GRUESA: valida la propuesta contra la politica de reembolso antes de tocar dinero
feedback_loop        aprobaciones/rechazos humanos y correcciones alimentan el eval-set

Ejercicio 2 — El campo en blanco. Revisas la hoja de una feature nueva de un compañero y ves que fallback está vacío. La feature es un chatbot de preguntas frecuentes en la página de ayuda. Formula las preguntas que le harías para llenar ese campo, y explica por qué un fallback vacío es un problema aunque la feature sea "solo un chatbot de FAQ".

Ejercicio 3 — La hoja como frontera entre equipos. El equipo de AI Engineering entrega a Mercado un buscador semántico "listo para integrar". El equipo de plataforma va a ubicarlo. Explica qué partes de la hoja son responsabilidad de cada equipo, y por qué la hoja hace más limpia la colaboración entre ambos que si no existiera.

Resumen y siguiente paso

En esta lección consolidaste todo el módulo en un artefacto reutilizable: la hoja de propiedades de un componente de IA. Es la ficha técnica de una feature de IA —diez campos: ubicación, tolerancia, presupuesto de latencia y costo, eval, guardrail, fallback, cáscara determinista, lazo de datos— con cada campo apuntando al módulo que lo trabaja a fondo. La viste ejecutada para la búsqueda semántica de Mercado, y viste sus tres usos: es el índice de la guía (cada campo es un módulo), un contrato entre el equipo que construye el núcleo y el que lo ubica, y un checklist de completitud donde un campo en blanco es un frente del iceberg sin resolver. Y viste su frontera: la hoja describe cómo el componente se integra y se contiene, nunca cómo se construye por dentro —eso es AI Engineering—.

Antes de avanzar deberías poder: nombrar los diez campos de la hoja y el módulo de cada uno; llenar una hoja para una feature dada; explicar por qué un campo en blanco es un problema aunque la feature sea tolerante; y por qué hay una hoja por feature y no una por sistema.

La lección 8 es el mini-proyecto: vas a llenar una hoja de punta a punta para una feature real de Mercado —el generador "describe tu producto"— y a ejecutar las propiedades que este módulo te enseñó. Clasificarás su tolerancia, separarás su núcleo de su cáscara, demostrarás el contrato probabilístico (el assert exacto se rompe, el de propiedades pasa), verás a la cáscara bloquear un claim prohibido, y emitirás su hoja de propiedades con un brief de decisión. Todo lo del módulo, integrado en un solo entregable ejecutado —y sin construir el generador, porque eso es AI Engineering—.

Recursos

• Martin Fowler y Bharani Subramaniam, "Emerging Patterns in Building GenAI Apps" — martinfowler.com/articles/gen-ai-patterns. El catálogo de patrones se mapea casi uno a uno con los campos de la hoja (eval, guardrail, RAG como fallback de contexto). Es la versión "catálogo" de lo que la hoja organiza en una ficha. En inglés.
• Michael Nygard, "Documenting Architecture Decisions" (2011) — cognitect.com/blog/2011/11/15/documenting-architecture-decisions. La hoja de propiedades es pariente del ADR: un artefacto estandarizado que captura una decisión arquitectónica. El brief de decisión del proyecto se apoya en esta idea. En inglés.
• Anthropic, "Building Effective Agents" (2024) — anthropic.com/engineering/building-effective-agents. Útil para llenar bien los campos de contención (guardrail, fallback, cáscara) de la hoja de un agente. En inglés.
• Chip Huyen, AI Engineering (O'Reilly, 2024). Su recorrido por los componentes de un sistema con modelos de fundación es, en la práctica, un recorrido por los campos de la hoja desde el lado de la construcción del núcleo —el complemento del lado de integración que esta guía enseña—. En inglés.