0Pricing
AI Engineering Academy · Lezione

Progettazione dell’architettura di produzione

Scelga un progetto conclusivo, delinei l’architettura completa includendo pipeline RAG, livello dell’agente, caching, osservabilità e API, quindi documenti le decisioni progettuali e i compromessi.

Progettazione dell’architettura di produzione è una lezione AI Engineering Academy gratuita su CoddyKit. Questa è la lezione 1 di 4. Puoi leggere la lezione completa qui gratuitamente — poi esercitati direttamente nel browser con un editor di codice integrato e un tutor IA disponibile 24/7. Fa parte del percorso di apprendimento AI Engineering Academy, e i tuoi progressi si sincronizzano tra il web e l'app CoddyKit. Il corso AI Engineering Academy include 4 lezioni in totale.

Scegliere un progetto finale

Il progetto finale riunisce tutti gli elementi del percorso: RAG, agenti, streaming, caching, osservabilità e sicurezza. Un buon progetto finale è significativamente complesso — richiede almeno tre componenti IA distinti — ma ha un ambito abbastanza limitato da poter essere rilasciato in pochi giorni anziché in pochi mesi. Esempi classici sono: un assistente Q&A su documenti pronto per la produzione, un agente di ricerca autonomo con supervisione umana o una pipeline aziendale per l'estrazione dei dati.

Identificare i componenti del sistema

Inizi elencando i diversi componenti necessari al sistema. Un progetto di ingegneria IA per la produzione include in genere: un livello di ingestione (caricamento dei documenti, suddivisione in chunk, generazione degli embedding, indicizzazione del vector store), un livello di recupero (ricerca ibrida, riordinamento), un livello dell'agente (function calling, esecuzione degli strumenti), un livello API (backend FastAPI, endpoint di streaming) e un livello di osservabilità (tracing, metriche, avvisi). Prima di scrivere il codice, abbozzi il flusso dei dati tra questi componenti.

# Component inventory for a Document QA Assistant:
COMPONENTS = [
    'document_ingestion',   # PDF/Word -> chunks -> embeddings -> pgvector
    'hybrid_retriever',     # BM25 + dense + RRF
    'reranker',             # Cohere rerank
    'qa_agent',             # GPT-4o with RAG + function calling
    'semantic_cache',       # Redis + embedding similarity
    'streaming_api',        # FastAPI StreamingResponse
    'tracing',              # LangSmith or Langfuse
    'prompt_injection_filter', # Input sanitization
    'eval_pipeline',        # Automated quality scoring
]

Scegliere lo stack giusto

Scelga la tecnologia in base alla familiarità del team e ai requisiti effettivi del sistema, non alla novità. Uno stack predefinito ragionevole comprende: FastAPI per il livello API, pgvector per l'archiviazione dei vettori (riutilizza l'infrastruttura PostgreSQL esistente), LangChain LCEL per la composizione delle pipeline, Redis per il caching semantico e lo stato dei limiti di frequenza, LangSmith per il tracing e PostgreSQL per i dati degli utenti e i risultati delle valutazioni. Aggiunga componenti solo quando le opzioni più semplici non soddisfano i requisiti.

# Technology decisions and their rationale
STACK = {
    'api':           ('FastAPI',    'Async support, OpenAPI docs, streaming easy'),
    'vector_store':  ('pgvector',   'Already on PostgreSQL, no extra infra'),
    'llm_primary':   ('gpt-4o',     'Best quality for the use case'),
    'llm_fallback':  ('claude-3.5', 'Different provider for resilience'),
    'cache':         ('Redis',      'Sub-ms lookup, TTL support built-in'),
    'tracing':       ('LangSmith',  'Native LangChain integration'),
    'embedding':     ('text-embedding-3-small', 'Good quality, low cost'),
    'reranker':      ('Cohere',     'Best-in-class rerank API'),
}

Disegnare il diagramma dell'architettura

Documenti l'architettura del sistema con un diagramma del flusso dei dati che mostri ogni componente, i dati che fluiscono tra di essi e la direzione del flusso. Includa sia il percorso di ingestione (offline: documenti → chunk → embedding → vector store) sia il percorso delle query (online: query dell'utente → verifica della cache → recupero → reranking → LLM → risposta in streaming). Questo diagramma è la guida principale per l'implementazione e aiuta i nuovi membri del team a comprendere immediatamente il sistema.

# Data flow (ASCII art):
#
# INGESTION PATH (offline):
# Documents --> Loader --> Chunker --> Embedder --> pgvector
#                                             |
#                                         BM25 index
#
# QUERY PATH (online):
# User Query
#    |-> Semantic Cache (hit: return) -> miss:
#    |-> Hybrid Retriever (BM25 + dense)
#    |-> Cohere Reranker
#    |-> LangChain LCEL Chain
#    |-> GPT-4o (streaming) --> FastAPI StreamingResponse
#    |-> LangSmith (trace every step)

Definire in anticipo i contratti API

Definisca gli endpoint API e i relativi schemi di richiesta e risposta in FastAPI prima di implementare la logica del backend. In questo modo crea un contratto tra l'API e gli eventuali client frontend e rende possibile lo sviluppo parallelo. Documenti ogni endpoint con descrizioni OpenAPI. Come minimo, definisca endpoint per: ingestione dei documenti, chat/query, cronologia delle conversazioni, risultati delle valutazioni e stato del sistema.

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI(title='Document QA Assistant', version='1.0')

class QueryRequest(BaseModel):
    question: str
    conversation_id: str | None = None
    max_chunks: int = 5
    stream: bool = True

class QueryResponse(BaseModel):
    answer: str
    sources: list
    cached: bool
    latency_ms: int
    trace_id: str

@app.post('/query', response_model=QueryResponse)
async def query_endpoint(request: QueryRequest):
    pass  # implementation next lesson

Stimare e preventivare i costi

Stimi il costo mensile delle API del sistema prima di scrivere una sola riga di codice backend. Calcoli: utenti attivi giornalieri previsti × query per utente × token medi per query. Per un sistema con 100 DAU, 10 query al giorno e 3.000 token per query ai prezzi di GPT-4o, si tratta di 3 milioni di token al giorno, ovvero circa 45 $ al giorno o 1.350 $ al mese. Questa stima indica se il sistema è economicamente sostenibile e quali ottimizzazioni (caching, model routing) vale la pena implementare.

# Cost estimation model
DAU = 100           # daily active users
QPD = 10            # queries per user per day
TOKENS_PER_QUERY = {
    'prompt_tokens': 2000,  # system + context + question
    'completion_tokens': 500
}

PRICE_GPT4O_INPUT = 2.50 / 1_000_000   # per token
PRICE_GPT4O_OUTPUT = 10.00 / 1_000_000  # per token

daily_cost = DAU * QPD * (
    TOKENS_PER_QUERY['prompt_tokens'] * PRICE_GPT4O_INPUT +
    TOKENS_PER_QUERY['completion_tokens'] * PRICE_GPT4O_OUTPUT
)
print(f'Daily: ${daily_cost:.2f}, Monthly: ${daily_cost * 30:.2f}')

Pianificare la pipeline di ingestione

Progetti la pipeline di ingestione come un processo batch offline eseguito su richiesta o secondo una pianificazione. Definisca i tipi di documento supportati (PDF, DOCX, HTML, testo semplice), la strategia di suddivisione in chunk, il modello di embedding e i campi di metadati da memorizzare insieme a ciascun vettore. I metadati sono fondamentali per il recupero filtrato: senza di essi non può limitare la ricerca ai documenti di uno specifico intervallo di date, autore o categoria.

from dataclasses import dataclass
from typing import Optional

@dataclass
class ChunkMetadata:
    doc_id: str
    source_file: str
    page_number: Optional[int]
    section_title: Optional[str]
    created_at: str
    author: Optional[str]
    doc_type: str  # 'pdf', 'docx', 'html'

# Ingestion config
INGESTION_CONFIG = {
    'chunk_size': 800,
    'chunk_overlap': 100,
    'embedding_model': 'text-embedding-3-small',
    'embedding_dimensions': 1536,
    'batch_size': 100,  # chunks per embedding API call
}

Decisioni sull'architettura di sicurezza

Prenda le decisioni relative alla sicurezza fin dall'inizio, invece di aggiungerle in un secondo momento. Definisca: come vengono autenticati gli utenti (JWT, API keys), quali dati possono essere recuperati da ciascun utente (sicurezza a livello di riga nelle query pgvector), come viene rilevata la prompt injection, quali controlli vengono applicati agli output e quali azioni richiedono una conferma a più fattori. Ogni decisione ha implicazioni sulle prestazioni che influenzano le scelte architetturali dell'intero sistema.

SECURITY_DECISIONS = {
    'auth': 'JWT with 24h expiry',
    'data_isolation': 'tenant_id column in all vector metadata, filter on every query',
    'injection_detection': 'rule-based pre-filter + LLM secondary check for complex inputs',
    'output_scanning': 'check for PII, system prompt leakage patterns',
    'destructive_actions': 'require confirmation token for delete operations',
    'rate_limiting': '20 queries/minute per user, 429 with Retry-After header',
    'key_storage': 'AWS Secrets Manager, rotated every 90 days'
}

Definire le metriche di successo

Definisca come si presenta il successo del sistema prima di realizzarlo. Un insieme di criteri di successo concreti e misurabili mantiene lo sviluppo focalizzato e fornisce criteri chiari per decidere se procedere al deployment. Includa metriche per: qualità (punteggio della valutazione sul set di test), latenza (TTFT p95 e totale), costo (obiettivo di costo per query) e affidabilità (SLA di disponibilità). Pubblichi questi obiettivi nel README del progetto, così che tutti i collaboratori condividano lo stesso riferimento.

SUCCESS_METRICS = {
    # Quality
    'min_correctness_score': 4.0,       # out of 5, LLM-as-judge
    'min_retrieval_hit_rate': 0.85,     # top-5 chunk contains answer
    # Latency
    'p95_ttft_ms': 800,                 # time to first token
    'p95_total_latency_ms': 8000,       # full response
    # Cost
    'max_cost_per_query_usd': 0.05,     # $0.05 per Q&A
    # Reliability
    'target_uptime': 0.999,             # 99.9%
    'cache_hit_rate_target': 0.25,      # 25% queries served from cache
}

Documentare i compromessi architetturali

Ogni decisione architetturale comporta dei compromessi. Li documenti esplicitamente in un Architecture Decision Record (ADR): quale decisione è stata presa, quali alternative sono state valutate e perché è stata scelta questa opzione. Ad esempio: «Abbiamo scelto pgvector invece di Pinecone perché utilizziamo già PostgreSQL, riducendo il carico operativo. Compromesso: la scalabilità massima è limitata a circa 10 milioni di vettori senza sharding». I futuri membri del team apprezzeranno questa trasparenza.

# Architecture Decision Records (ADRs):
#
# ADR-001: Use pgvector for vector storage
# Decision: pgvector in existing PostgreSQL
# Alternatives: Pinecone, Weaviate, Qdrant
# Reason: No new infra, row-level security native, familiar operations
# Trade-offs: Limited to ~5M vectors before performance degrades
#
# ADR-002: GPT-4o as primary model
# Decision: gpt-4o for all user-facing queries
# Alternatives: gpt-4o-mini (cheaper), Claude (alternative)
# Reason: Highest quality for use case, Claude as fallback
# Trade-offs: $0.04/query vs $0.002 for gpt-4o-mini

Abbozzare la topologia di deployment

Definisca come verrà distribuito il sistema prima di scrivere il codice dell'infrastruttura. Associ ogni componente a un'unità di deployment: il backend FastAPI come container Docker, la pipeline di ingestione come servizio worker separato, pgvector come istanza PostgreSQL gestita e Redis come cache gestita. Specifichi quali componenti sono stateless (possono essere scalati orizzontalmente) e quali stateful (richiedono strategie di scaling attente). Un diagramma di deployment evita ore di rielaborazione in seguito.

# Deployment topology:
#
# Internet -> Load Balancer (AWS ALB)
#                |
#            FastAPI API  (stateless, 2-4 containers, auto-scale)
#                |
#         +------+------+
#         |             |
#    pgvector        Redis Cache
#  (AWS RDS Postgres) (Elasticache)
#         |
#    Ingestion Worker  (separate container, manual trigger)
#         |
#    LangSmith (external SaaS, traces only)
#
# All containers in same VPC, no public access to DB/cache

Verifica rapida

Verifichi la sua comprensione della progettazione dell'architettura di sistemi IA per la produzione.

Riepilogo della lezione

In questa lezione ha imparato che l'inventario dei componenti e i diagrammi del flusso dei dati creano una visione architetturale condivisa prima dell'inizio della programmazione, che i contratti API definiti in anticipo consentono lo sviluppo parallelo e rendono espliciti i requisiti e che le metriche di successo definite in anticipo mantengono il team allineato sugli obiettivi di qualità, latenza, costo e affidabilità. Ora implementeremo le funzionalità principali di RAG e degli agenti.

Domande Frequenti

La lezione «Progettazione dell’architettura di produzione» è gratuita?

Sì — il testo completo di «Progettazione dell’architettura di produzione» è gratuito qui sul web. Per esercitarvi in modo interattivo (un editor di codice integrato e un tutor IA 24/7) e sbloccare il resto del corso AI Engineering Academy, passa a CoddyKit PRO. Il corso AI Engineering Academy include 4 lezioni in totale.

Cosa imparerò in «Progettazione dell’architettura di produzione»?

Scelga un progetto conclusivo, delinei l’architettura completa includendo pipeline RAG, livello dell’agente, caching, osservabilità e API, quindi documenti le decisioni progettuali e i compromessi. Eserciti AI Engineering Academy con codice pratico che esegui direttamente nel browser, e un tutor IA 24/7 risponde alle tue domande mentre lavori sulla lezione.

Ho bisogno di esperienza per iniziare AI Engineering Academy?

Non è richiesta alcuna esperienza precedente. AI Engineering Academy su CoddyKit è strutturato per principianti e studenti avanzati, quindi puoi iniziare da qui o dall'inizio e procedere al tuo ritmo. Questa è la lezione 1 di 4.

Quanto tempo richiede la lezione «Progettazione dell’architettura di produzione»?

La maggior parte delle lezioni CoddyKit richiede circa 5–10 minuti. Ogni lezione è breve e interattiva, quindi fai progressi costanti e riprendi esattamente da dove hai lasciato su web e app.

Posso scrivere ed eseguire codice in questa lezione AI Engineering Academy?

Sì. Ogni lezione AI Engineering Academy include un editor di codice integrato, quindi scrivi ed esegui codice reale direttamente nel tuo browser e ricevi feedback istantaneo dall'IA — nessuna configurazione locale necessaria.

Tutte le lezioni di questo corso

  1. Progettazione dell’architettura di produzione
  2. Implementazione delle funzionalità fondamentali di RAG e degli agenti
  3. Rafforzamento: sicurezza, caching e affidabilità
  4. Valutazione, deployment e retrospettiva
← Torna a AI Engineering Academy