# aws-ai-reference-architectures Seis arquiteturas de IA na AWS com decisões, custo S/M/L e Terraform - URL: https://fernando.moretes.com/open-source/aws-ai-reference-architectures - Markdown: https://fernando.moretes.com/open-source/aws-ai-reference-architectures/guide.md?lang=pt - GitHub: https://github.com/fernando-moretes/app-aws-ai-reference-architectures - Homepage: https://fernando-moretes.github.io/app-aws-ai-reference-architectures/ - Language: HCL - Topics: ai, architecture, aws, bedrock, github-actions, mlops, moretes, portfolio, reference-architecture, sagemaker, solution-architecture, terraform, well-architected - Stars: 0 - Forks: 0 - Updated: 2026-09-29T16:22:14Z --- Seis arquiteturas de referência para cargas de IA na AWS (RAG, multi-agente, streaming, event-driven, fine-tuning e agente seguro), cada uma com diagrama Mermaid, decisões no formato MADR, custo em três escalas, revisão Well-Architected e um esqueleto Terraform que dá para ler em 10 minutos. ## Por que este repositório existe O material sobre IA na AWS costuma cair em um de dois extremos. De um lado, o notebook de exemplo: um arquivo, nenhuma IaC, nenhuma linha sobre IAM ou rede. Funciona na demo e não sobrevive à primeira revisão de segurança. Do outro, o white paper de 200 páginas: correto, completo e impossível de usar numa reunião de design de uma hora. A pergunta que me interessa não é "qual serviço usar?", é "o que eu preciso decidir antes de escrever a primeira linha, e quanto isso vai custar para manter?". Este repositório fica no meio do caminho: seis arquiteturas **opinativas**, detalhadas o bastante para servir de ponto de partida de um design real e curtas o bastante para caber numa leitura antes da reunião. Cada arquitetura responde às mesmas oito perguntas, na mesma ordem: problema, componentes e por quê, diagrama, as 3–5 decisões que importam (com alternativas), custo mensal em USD nas escalas S, M e L, achados Well-Architected nos seis pilares, trade-offs (quando usar e quando **não** usar) e o esqueleto Terraform. A estrutura fixa é deliberada: quem já leu uma sabe onde procurar em todas as outras. ## As seis arquiteturas - **01 RAG com Bedrock + OpenSearch:** Q&A interno sobre documentos e bases de conhecimento. - **02 Orquestração multi-agente:** Bedrock Agents + Step Functions para fluxos longos que precisam de estado durável. - **03 Inferência em streaming:** API Gateway + Lambda + streaming do Bedrock para interfaces de chat token a token. - **04 Processamento event-driven:** EventBridge + SQS + Lambda + Bedrock para classificação, enriquecimento e moderação assíncronos. - **05 Pipeline de fine-tuning:** SageMaker + S3 + MLflow para modelos customizados sobre foundation models. - **06 Sistema agêntico seguro:** Bedrock Agents + Guardrails + VPC para agente multi-tenant em produção com guardrails rígidos. ## Como ler, conforme o que você precisa O repositório não foi pensado para leitura de ponta a ponta. Cada pasta em `architectures/` é autocontida, e o ponto de entrada muda com a pergunta que você traz: - **Design novo:** leia a arquitetura correspondente inteira e copie a seção de trade-offs para o seu design doc. É ali que estão as condições em que o padrão deixa de valer. - **Revisão de ambiente existente (brownfield):** abra direto a seção Well-Architected e compare com o que está rodando. Os achados estão organizados pelos seis pilares, então a conversa com o time vira checklist. - **Conversa de custo:** as tabelas trazem três dimensionamentos (S, M, L) com as premissas de entrada escritas. A premissa importa mais que o número; mude o volume e refaça a conta. - **Inspiração para ADR:** as decisões seguem o formato [MADR](https://adr.github.io/madr/). Copie, adapte o contexto e registre a sua. Na prática, o uso mais frequente é o segundo: pegar um sistema que já existe e descobrir o que ficou para trás em segurança ou operação. ## Do Markdown ao leitor: como o repositório é publicado O conteúdo mora em Markdown, Mermaid e HCL; a esteira valida e publica em dois destinos. ### 📁 Repo: conteúdo - architectures/ 6 pastas: doc + Mermaid + Terraform (storage) - docs/ MkDocs Material (storage) - frontend/ landing estática sem dependências (frontend) ### 🔧 GitHub Actions: CI - MkDocs build strict lint + build do frontend (ci) - CodeQL, Trivy fs, Gitleaks, dependency review (security) ### 📤 Saída: publicação - GitHub Pages site de documentação (edge) - Vercel landing do catálogo (edge) ### Fluxos - author -> arch: edita - arch -> build: valida - docs -> build: build estrito - fe -> build: lint + npm audit - build -> sec: varredura - build -> pages: deploy - fe -> vercel: integração Git ## Como usar 1. **Clone o repositório**: `git clone https://github.com/fernando-moretes/app-aws-ai-reference-architectures.git` e entre na pasta. Se só quer ler, o site de documentação no GitHub Pages tem o mesmo conteúdo renderizado. 2. **Escolha a arquitetura pelo caso de uso**: Use a tabela do README: Q&A sobre documentos vai para a 01, fluxo longo com estado vai para a 02, chat com streaming vai para a 03, processamento assíncrono vai para a 04, modelo customizado vai para a 05, agente multi-tenant vai para a 06. 3. **Leia decisões e trade-offs antes do Terraform**: As 3–5 decisões de cada pasta dizem por que cada serviço está ali e qual alternativa foi descartada. Pular essa parte e ir direto ao HCL é copiar a resposta sem a pergunta. 4. **Valide o esqueleto Terraform localmente**: Dentro da pasta da arquitetura, `terraform init -backend=false` seguido de `terraform validate` confirma a fiação dos recursos sem tocar em conta nenhuma. Nomes, tags, rede, policies de IAM e remote state são seus para adaptar. 5. **Rode a documentação localmente (opcional)**: O site usa MkDocs Material. Instale com `pip install mkdocs-material` e rode `mkdocs serve`; o CI usa build estrito, então use `mkdocs build --strict` antes de abrir PR. _Quickstart: clonar, validar um esqueleto e subir a documentação_ ```bash git clone https://github.com/fernando-moretes/app-aws-ai-reference-architectures.git cd app-aws-ai-reference-architectures # Valida a fiação do Terraform sem backend e sem credenciais cd architectures/01-rag-bedrock-opensearch terraform init -backend=false terraform validate cd ../.. # Documentação local (MkDocs Material) pip install mkdocs-material mkdocs serve # http://127.0.0.1:8000 mkdocs build --strict # o mesmo build que o CI roda ``` > **Esqueleto não é módulo:** O HCL mostra recursos e fiação, não um módulo pronto para `terraform apply` em produção. Ele não traz remote state, convenção de tags nem policies de IAM fechadas para o seu ambiente. Aplicar como está é herdar decisões de rede e permissão que não foram tomadas para você, e esse é o tipo de dívida que só aparece na auditoria. ## A esteira em volta do conteúdo Repositório público de arquitetura tem um risco que pouca gente trata: um exemplo com segredo vazado ou dependência vulnerável vira referência copiada por outras pessoas. Por isso o conteúdo passa pelas mesmas verificações que eu exigiria de código de produção. **Documentação:** build estrito do MkDocs. Link quebrado ou página órfã derruba o build, em vez de virar 404 silencioso no site. **Frontend:** a landing é estática e sem dependências de runtime; mesmo assim passa por lint, build e `npm audit`. **Segurança:** CodeQL, dependency review, Trivy em modo filesystem e Gitleaks para segredo. O Gitleaks é o que mais importa aqui, porque esqueleto Terraform é exatamente o lugar onde alguém cola uma chave para testar e esquece. **Manutenção:** Dependabot para GitHub Actions e dependências do frontend. O deploy da landing sai pela integração Git da Vercel, com preview por PR. O `OPERATIONS.md` descreve o fluxo completo e os segredos necessários para quem fizer fork. ## Perguntas frequentes ### Os números de custo servem para orçamento? Servem para ordem de grandeza e para a conversa inicial. As premissas de cada escala estão escritas; se o seu volume de tokens ou de documentos for diferente, refaça a conta com a calculadora oficial da AWS antes de comprometer orçamento. ### A revisão Well-Architected substitui a ferramenta oficial? Não. Ela aponta os achados mais salientes de cada padrão. Antes de qualquer lançamento em produção, rode a revisão formal no AWS Well-Architected Tool sobre a sua carga real. ### Meu caso não cabe em nenhuma das seis. E agora? Seis padrões cobrem a maior parte do que vejo na prática, mas não tudo. Abra uma issue descrevendo o caso de uso; correções aos padrões existentes também são bem-vindas, conforme o `CONTRIBUTING.md`. ## Referências - [GitHub: fernando-moretes/app-aws-ai-reference-architectures](https://github.com/fernando-moretes/app-aws-ai-reference-architectures) - [Documentation site (GitHub Pages)](https://fernando-moretes.github.io/app-aws-ai-reference-architectures/) - [MADR: Markdown Architectural Decision Records](https://adr.github.io/madr/) - [AWS Well-Architected Framework](https://aws.amazon.com/architecture/well-architected/) - [MkDocs Material](https://squidfunk.github.io/mkdocs-material/) ## Para quem é Use este repositório quando você precisa levar a uma reunião de design um ponto de partida com decisões, custo e trade-offs já escritos, ou quando quer revisar um sistema de IA na AWS que já existe contra um checklist por pilar. Não use como biblioteca de módulos Terraform nem como substituto da revisão formal Well-Architected: o valor está nas decisões e nas condições em que cada padrão deixa de valer, não no HCL. ## Links - [GitHub repository](https://github.com/fernando-moretes/app-aws-ai-reference-architectures) - [Homepage](https://fernando-moretes.github.io/app-aws-ai-reference-architectures/)