Módulo 1: Genai In Production Vs A Notebook

1. Introducción a la guía: la octava pieza del ecosistema

Descripción

Si llegaste hasta aquí, Andes Cargo ya tiene un sistema de producción real, no un prototipo. Un bucket S3 (andes-cargo-shipment-docs) que recibe manifiestos de envío. Una función Lambda, process-shipment-manifest, que los parsea. Una tabla DynamoDB, Shipments, con partition key shipmentId, que los persiste. Un bus de eventos, andes-cargo-events, donde ShipmentProcessed se publica cada vez que un envío se procesa con éxito. Un workflow de Step Functions, ShipmentManifestWorkflow, que encadena validación, procesamiento y notificación con reintentos reales. Una API REST, andes-cargo-api, que expone GET /shipments/{shipmentId}. Todo esto declarado en Terraform dentro de andes-cargo-infra/, corriendo a través de un pipeline de GitHub Actions con un security gate (policy-check/iac-scan/verify-artifact) y un cost gate (cost-estimate/cost-check/cost-tags) que ningún cambio malo puede cruzar sin ser detenido.

Esta guía no reconstruye nada de eso. Le agrega a Andes Cargo su primera carga de trabajo de inteligencia artificial generativa — y, con ella, una pregunta que ninguna de las siete guías anteriores tuvo que contestar: ¿qué cambia cuando una pieza de tu sistema de producción ya no es determinista? process-shipment-manifest siempre produce el mismo resultado para la misma entrada. Un modelo de lenguaje, no. Esa única diferencia — determinismo contra no determinismo — es el hilo que atraviesa las ocho lecciones de este módulo, y las ocho siguientes de esta guía.

Conexión con el módulo

Este es el módulo de apertura de una guía de ocho módulos, y esta es su primera lección. Su trabajo, antes de tocar Bedrock, guardrails o costo por token, es tender el puente: qué heredas exactamente (esta lección), por qué "funciona en un notebook" no es lo mismo que "funciona en producción" (lección 2), cuál es el problema real de Andes Cargo que justifica esta guía (lección 3), dónde termina esta guía y empieza AI Engineering (lección 4), qué existe hoy, de verdad, en la infraestructura heredada (lección 5), qué modelos ofrece Bedrock en 2026 y por qué el camino barato sigue siendo el default (lección 6), qué pasa cuando de verdad intentas tocar Bedrock desde este laboratorio $0 (lección 7), y el documento que cierra el módulo: el ADR que fija, por escrito, la decisión de arquitectura que sostiene toda la guía (lección 8).

El mapa completo: los 8 módulos de esta guía

   GENAI EN PRODUCCIÓN SOBRE AWS — LOS 8 MÓDULOS

   M1  GenAI en producción vs. un notebook   ← estás aquí: el puente, la frontera, el ADR
   M2  El modelo de costo de Bedrock          on-demand/Provisioned/Batch, la calculadora propia
   M3  IaC para un endpoint de IA              bedrock.tf, validate/plan reales, el módulo más EJECUTADO
   M4  Guardrails de Bedrock y defensa en profundidad   6 políticas + scrubber propio
   M5  Asegurando la carga de IA               el security gate heredado, extendido
   M6  FinOps para tokens                      el cost gate heredado, extendido
   M7  Observabilidad, latencia y evals         SLI/SLO de IA, el arnés de smoke test
   M8  Capstone: el extractor GenAI de Andes Cargo   el sistema completo, el ledger de honestidad

#	Módulo	Qué construye	Peso EJECUTADO
1	GenAI en producción vs. un notebook	El puente, la frontera con AI Engineering, el ADR	Bajo — módulo de vocabulario y decisión
2	El modelo de costo de Bedrock	La calculadora propia de costo por token	Medio — Infracost heredado + calculadora nueva
3	IaC para un endpoint de IA	`bedrock.tf`, `modules/bedrock-guardrail/`, el rol IAM	Alto — `validate`/`plan` reales, sin LocalStack
4	Guardrails de Bedrock y defensa en profundidad	El guardrail gestionado en HCL + el scrubber propio	Alto — HCL real + Python propio con `pytest`
5	Asegurando la carga de IA	`conftest`/Trivy/`cosign` extendidos, no reconstruidos	Alto — mismas herramientas $0, Terraform nuevo
6	FinOps para tokens	El cost gate extendido con presupuesto de tokens	Alto — misma mecánica, política nueva
7	Observabilidad, latencia y evals	CloudWatch real + el arnés de smoke test	Medio — logging real, salida del modelo representativa
8	Capstone: el extractor GenAI	El sistema completo, con el ledger de honestidad	Mixto, declarado línea por línea

Fíjate en la progresión: primero instalas el vocabulario y la decisión (M1) — el LLM es un camino de escalamiento, no el default —, después entiendes cuánto cuesta de verdad (M2) antes de declarar un solo recurso, después declaras la infraestructura (M3), le pones guardrails (M4), la aseguras (M5) y le pones presupuesto (M6) reusando los gates que ya existen, la observas (M7), y cierras con el capstone (M8) que recorre el sistema completo de punta a punta, con la honestidad exacta de qué corrió de verdad y qué quedó representativo.

El mapa de este módulo: las 8 lecciones

#	Lección	Qué practicas
1	Introducción (esta)	El mapa completo, qué se hereda de las siete guías anteriores, qué existe al cerrar el M8
2	Un notebook y un sistema en producción no son el mismo problema	Por qué "funciona en el playground de Bedrock" no dice nada sobre costo, seguridad ni confiabilidad
3	La carga de IA de Andes Cargo	El problema real: manifiestos en texto libre que `process-shipment-manifest` no puede leer
4	La frontera con AI Engineering, dicha en voz alta	Qué construye esta guía frente a qué construye AI Engineering — sin ambigüedad, desde la lección 4
5	Manos a la obra: inventario de lo que ya existe	Ejecutado (representativo): `awslocal events list-rules`, `lambda list-functions`, `iam list-roles`
6	Bedrock, panorama 2026	Amazon Nova, Claude, Llama, Mistral — verificado contra fuentes de 2026, con URLs
7	Manos a la obra: el intento honesto contra Bedrock en LocalStack	Ejecutado (el intento) + representativo (la conclusión): `awslocal bedrock list-foundation-models`
8	Proyecto: el mapa de la carga de IA de Andes Cargo	Ejecutado (el documento): un ADR corto, la decisión que gobierna el resto de la guía

Analogía: llegar al octavo restaurante de una cadena que ya funciona

Imagina que te contratan como gerente del octavo local de una cadena de restaurantes que ya tiene siete locales operando bien: la cocina está estandarizada, el proveedor de insumos está negociado, el sistema de reservas funciona, hay un protocolo de seguridad alimentaria auditado, y hay un presupuesto mensual que nadie se salta sin aprobación. Tu trabajo no es reinventar ninguna de esas siete cosas — es abrir el octavo local agregando un plato nuevo al menú, uno que requiere un ingrediente que ningún local anterior necesitó: algo que se cocina distinto cada vez, con un proveedor que cobra por porción servida, no por hora de cocina encendida. Ese plato nuevo es la carga de IA generativa de Andes Cargo. El resto del restaurante — la cocina, el proveedor, las reservas, el protocolo, el presupuesto — es exactamente lo que las siete guías anteriores ya construyeron, y esta guía hereda sin volver a cocinar.

Qué heredas, sin que se vuelva a explicar

Esta guía asume, sin repetirlo, siete piezas completas del ecosistema:

De aws-core-services-guide (transitivo, vía terraform-and-iac-guide): qué es IAM de una sola cuenta, y los cuatro servicios que sostienen el caso — S3, DynamoDB, Lambda, IAM — con process-shipment-manifest, la tabla Shipments y los roles LambdaManifestProcessorRole/AppServerRole como el punto de partida literal.
De terraform-and-iac-guide: el proyecto andes-cargo-infra/ completo, los módulos modules/s3-bucket//modules/iam-role/, el ciclo init/plan/apply/destroy. Esta guía agrega bedrock.tf y modules/bedrock-guardrail/ al mismo proyecto, con la misma convención de nombrado.
De aws-serverless-and-containers-guide: el bus andes-cargo-events, la API REST andes-cargo-api, ShipmentManifestWorkflow en Step Functions, Lambda avanzado (layers, variables de entorno, alias). El extractor de esta guía es una función Lambda más, disparada por un evento del mismo bus.
De cicd-and-gitops-on-aws-guide: act como motor de ejecución local, ci.yml/apply.yml, el patrón plan-en-PR/apply-en-merge.
De cloud-security-and-guardrails-guide: el security gate completo (policy-check/iac-scan/verify-artifact), el directorio policy/, THREAT-MODEL.md/RISK-MAP.md. Esta guía agrega políticas nuevas a ese mismo directorio, nunca reemplaza las que ya existen.
De finops-and-cost-guardrails-guide: el cost gate completo (cost-estimate/cost-check/cost-tags), el directorio cost-policy/, Infracost ya instalado y su límite de autenticación ya documentado — este diseño hereda ese hallazgo, no lo reinvestiga.
De sre-and-incident-response-guide (transitivo): el vocabulario SLI/SLO/error budget, aplicado ya una vez a un Lambda y una API. Esta guía lo reaplica a métricas de IA, no lo reintroduce desde cero.

Y una octava pieza, AI Engineering, el ecosistema completo — no una guía de AWS, el ecosistema entero que precede a este en el grafo (BACKEND → AI ENGINEERING → AWS CLOUD). El alumno llega sabiendo construir sistemas de IA: prompting, function calling, RAG, agentes. Esta guía toma eso como dado, y no lo repite — lección 4 fija esa frontera con precisión.

Si alguna de estas siete piezas no te suena firme, la señal es volver a la guía correspondiente antes de seguir. Ninguna lección de aquí en adelante vuelve a explicar qué es un resource de Terraform, un evento de EventBridge, o un job de un pipeline — solo cómo se le agrega una carga de IA generativa.

Lo genuinamente nuevo de esta guía

Ningún módulo de esta guía reescribe un recurso de negocio ya declarado. El bucket sigue siendo andes-cargo-shipment-docs, la tabla sigue siendo Shipments con partition key shipmentId, la función process-shipment-manifest sigue siendo la primera línea de defensa. Lo nuevo, siempre en la capa de IA, nunca en la de negocio:

  andes-cargo-infra/
  ├── THREAT-MODEL.md / RISK-MAP.md      (heredado — este módulo no los edita)
  ├── policy/                             (heredado — M5 agrega bedrock-least-privilege.rego)
  ├── cost-policy/                        (heredado — M6 agrega bedrock-budget.rego)
  ├── bedrock.tf                          ← NUEVO (M3)
  ├── modules/
  │   ├── s3-bucket/  ├── iam-role/  ├── oidc-provider/   (heredados, sin cambios)
  │   └── bedrock-guardrail/              ← NUEVO (M3)
  ├── functions/
  │   ├── process-shipment-manifest/      (heredada — M1.3 la retoma, sin reescribirla)
  │   └── extract-shipment-manifest-fields/   ← NUEVO (M3-M4)
  ├── guardrails/
  │   ├── pre_invoke_checks.py            ← NUEVO (M4) — scrubber de PII
  │   └── post_invoke_checks.py           ← NUEVO (M4) — validador de esquema
  ├── scripts/
  │   └── bedrock_cost_estimate.py        ← NUEVO (M2) — calculadora de costo por token
  ├── evals/                              ← NUEVO (M7) — smoke test
  ├── GENAI-COST-PROFILE.md               ← NUEVO (M2) — complemento de COST-PROFILE.md
  └── ADR-001-llm-as-escalation-path.md   ← NUEVO (M1.8, esta lección lo anticipa)

El evento que dispara toda esta capa nueva tampoco existe todavía: ManifestParseFailed, publicado por process-shipment-manifest cuando un manifiesto llega en texto libre y el parseo clave=valor no puede leerlo. La lección 3 de este módulo lo presenta con el detalle completo del problema que resuelve.

El compromiso de honestidad de esta guía, resumido de entrada

Esta es la única guía del ecosistema donde ninguna lección invoca un modelo de verdad. Amazon Bedrock cobra por token, exige una cuenta AWS con método de pago activo, y el plan gratuito de LocalStack (Hobby) no lo incluye — solo el plan Ultimate, de pago. Nada de eso es una debilidad de esta guía: es la naturaleza exacta del servicio que enseña a operar, y se declara sin rodeos desde esta primera lección, no escondida al final.

Lo que sí corre de verdad, con herramientas $0 reales, sostiene la mayoría de los ocho módulos: terraform validate/plan de recursos Bedrock reales (M3 — confirmado por ejecución directa, sin necesitar LocalStack ni cuenta AWS, porque un recurso nuevo nunca necesita leer del state); un guardrail local, propio y determinista (M4); conftest/Trivy/cosign/Infracost, reusados de las guías hermanas (M5/M6); la calculadora de costo por token, código Python 100% determinista (M2); logging y métricas reales de CloudWatch (M7). Lo que queda representativo, siempre con la razón técnica exacta citada en el momento en que aparece: cualquier invocación real de Bedrock, el bloqueo real de un guardrail gestionado, el número en dólares de Infracost, y la latencia/calidad real de una respuesta de modelo. Esta lección solo lo anticipa — cada módulo lo declara de nuevo, en el punto exacto donde aplica.

Errores comunes

Asumir que esta guía va a "enseñar a usar Bedrock" en el sentido de escribir prompts (de expectativa). Qué pasa: alguien llega esperando aprender ingeniería de prompts, RAG o agentes sobre Bedrock, como continuación natural de un curso de AI Engineering. Cómo detectarlo: si tu pregunta al terminar la lección 4 sigue siendo "¿pero cómo escribo un mejor prompt?". Cómo corregirlo: esta guía opera infraestructura de IA — costo, seguridad, guardrails, observabilidad —, no construye la aplicación de IA en sí. La lección 4 fija esta frontera con una cita textual del propio diseño del ecosistema, y se repite cada vez que una lección roza la tentación de enseñar prompting en vez de infraestructura.

Saltarse una de las siete guías anteriores porque "esta ya explica lo que hace falta" (de flujo). Qué pasa: alguien sin aws-serverless-and-containers-guide llega a la lección 5 de este módulo y no reconoce andes-cargo-events, ShipmentManifestWorkflow ni EventBridgeAutomationRole. Cómo detectarlo: si un nombre como process-shipment-manifest o un archivo como bedrock.tf (que extiende, no reemplaza, andes-cargo-infra/) te resulta desconocido en su contexto. Cómo corregirlo: vuelve a la guía correspondiente de la lista de arriba. Esta guía asume las siete completas, sin excepción, desde esta primera lección.

Concluir, al leer "ninguna lección invoca un modelo de verdad", que esta guía no construye nada real (de lectura). Qué pasa: alguien lee el compromiso de honestidad de esta sección y decide que toda la guía es teórica. Cómo detectarlo: si tu resumen mental es "esta guía es puro PowerPoint". Cómo corregirlo: el M3 —infraestructura como código para un endpoint de IA— es, en proporción, el módulo con más peso ejecutado de toda esta guía: terraform validate/plan de un aws_bedrock_guardrail completo corre de verdad, sin LocalStack, sin cuenta AWS, sin token, porque declarar y planear un recurso nuevo nunca requiere conectividad con la API real. Lo único que no corre es la inferencia — el modelo respondiendo — que es, precisamente, la única pieza que esta guía existe para enseñarte a operar alrededor de, no a construir.

Ejercicios

Ejercicio 1 — Nombra las siete guías heredadas, sin mirar la tabla. De memoria, escribe los siete nombres de guía que esta guía asume completos, y qué pieza concreta de andes-cargo-infra/ aporta cada una.

Ver solución

aws-core-services-guide (transitivo) — process-shipment-manifest, la tabla Shipments, los roles base. terraform-and-iac-guide — el proyecto andes-cargo-infra/ completo, los módulos s3-bucket/iam-role. aws-serverless-and-containers-guide — el bus andes-cargo-events, la API andes-cargo-api, ShipmentManifestWorkflow. cicd-and-gitops-on-aws-guide — act, ci.yml/apply.yml. cloud-security-and-guardrails-guide — el security gate (policy-check/iac-scan/verify-artifact). finops-and-cost-guardrails-guide — el cost gate (cost-estimate/cost-check/cost-tags). sre-and-incident-response-guide (transitivo) — el vocabulario SLI/SLO/error budget. Si recordaste al menos cinco sin mirar, tienes clara la base sobre la que se construye toda esta guía.

Ejercicio 2 — Explica, en una frase, la única diferencia técnica que justifica una guía entera. Un colega pregunta por qué hace falta una guía de ocho módulos solo para "agregar un modelo de IA" a un sistema que ya funciona. Respóndele con la idea central de esta lección.

Ver solución

Una respuesta completa suena, más o menos, así: "Porque process-shipment-manifest es determinista —la misma entrada siempre produce la misma salida—, y todo lo que las siete guías anteriores enseñaron sobre costo predecible, seguridad verificable y 'Qué esperar' literal asume eso. Un modelo de lenguaje no es determinista: la misma entrada puede producir una salida distinta, cuesta por token en vez de por hora encendida, y necesita una capa de defensa que un recurso 'normal' de AWS nunca necesitó. Esa única diferencia —determinismo contra no determinismo— es lo que justifica ocho módulos nuevos, no un capítulo extra en una guía existente."

Ejercicio 3 — Ubica dónde vive cada pieza nueva en andes-cargo-infra/. Sin mirar el diagrama de esta lección, nombra al menos cuatro de los siete artefactos nuevos que esta guía agrega al proyecto, y en qué módulo aparece cada uno.

Ver solución

bedrock.tf y modules/bedrock-guardrail/ (M3); guardrails/pre_invoke_checks.py y guardrails/post_invoke_checks.py (M4); scripts/bedrock_cost_estimate.py (M2); policy/bedrock-least-privilege.rego (M5); cost-policy/bedrock-budget.rego (M6); evals/ (M7); GENAI-COST-PROFILE.md (M2) y ADR-001-llm-as-escalation-path.md (M1, el proyecto de esta misma lección introductoria). Si nombraste cuatro sin mirar, tienes clara la progresión módulo por módulo de esta guía.

Resumen y siguiente paso

En esta lección viste el mapa completo de los 8 módulos de esta guía, confirmaste qué se hereda sin repetirse de las siete guías anteriores del ecosistema — infraestructura, pipeline, security gate, cost gate, vocabulario SRE — y qué es genuinamente nuevo: siete artefactos de la capa de IA, ninguno de negocio. También viste, de entrada, el compromiso de honestidad de esta guía: es la única del ecosistema donde ninguna lección invoca un modelo de verdad, con la razón técnica exacta (Bedrock cobra por token y no está en el plan gratuito de LocalStack), y dónde sí corre código real: Terraform, Python, los gates heredados.

Antes de avanzar deberías poder: nombrar las ocho módulos en orden y qué construye cada uno; explicar por qué esta guía no repite las siete anteriores; y decir, sin dudar, la diferencia entre "invocar un modelo" (nunca ocurre aquí) y "declarar y planear la infraestructura de un modelo" (ocurre, de verdad, desde el M3).

La lección 2 instala la tesis central del módulo: por qué "funciona en el playground de Bedrock" no dice absolutamente nada sobre si esa misma llamada es segura, barata o confiable en producción — el eco deliberado de una lección que ya viste, con otras palabras, en las dos guías anteriores de este mismo ecosistema.

Recursos

terraform-and-iac-guide, aws-serverless-and-containers-guide, cicd-and-gitops-on-aws-guide, cloud-security-and-guardrails-guide, finops-and-cost-guardrails-guide, sre-and-incident-response-guide (NIEVA) — las seis guías cuyo trabajo completo esta guía hereda sin repetir.
src/paths/aws-cloud-ecosystem/STRATEGY.md — la posición de esta guía en el grafo del ecosistema, después de AI Engineering: "El alumno llega sabiendo construir sistemas de IA. No repite fundamentos: aprende a operarlos".
AWS — Amazon Bedrock — la página oficial del servicio que esta guía entera aprende a operar, punto de partida de la lección 6.
LocalStack Docs — Bedrock — la fuente exacta de por qué esta guía no puede invocar un modelo: "Included in Plans: Ultimate", sin Hobby.
src/paths/aws-cloud-ecosystem/VALIDACION.md — la auditoría de mercado que fija el peso y la posición de esta guía como diferenciador de cierre, no como puerta de entrada.

Siguiente →2. Un notebook y un sistema en producción no son el mismo problema