Azure AI Foundry Responsible AI Guardrails: una guida completa all'implementazione

nelle distribuzioni di ia azure in settori regolamentati, il modello è spesso lo stesso: il team perfeziona la pipeline rag, il datastore vettoriale e l'interfaccia utente di streaming – e poi distribuisce senza alcuna protezione. questa è sempre stata una mossa rischiosa, ma con la legge eu sull'ia ora in vigore, ha cambiato permanentemente il calcolo del rischio. ciò che una volta era un 'nice-to-have' è ora un requisito di conformità rigoroso per qualsiasi applicazione llm aziendale seria.

costruire applicazioni llm di livello produttivo non riguarda solo l'ottenimento della risposta corretta; si tratta di garantire la risposta sicura e responsabile. le organizzazioni, in particolare quelle nei settori finanziario, sanitario e pubblico in tutta europa, stanno affrontando allucinazioni di modelli, attacchi di iniezione di prompt, la generazione di contenuti dannosi e la violazione della proprietà intellettuale. questi non sono rischi astratti; si traducono direttamente in multe regolamentari, danni alla reputazione e una completa perdita di fiducia degli utenti.

questa guida fornisce un approccio completo, code-first, per la costruzione di un robusto livello di sicurezza ia responsabile su azure. andremo oltre i concetti di marketing e ci immergeremo in controlli di ingegneria concreti utilizzando due percorsi complementari: l'api di analisi autonoma azure ai content safety per uno screening rapido e basato su policy delle categorie di danno (e segnali opzionali di tipo jailbreak tramite shield_prompt su tale api), e azure openai service per i controlli a livello di distribuzione – prompt shields, groundedness detection e protected material detection – che si abilitano e si leggono dalla risposta di completamento di azure openai, non solo da contentsafetyclient. vi mostrerò come comporli in un'unica catena di middleware fastapi modulare, provisionare l'intero stack con terraform e mappare ogni guardrail alla sua corrispondente obbligazione ai sensi della legge eu sull'ia.

questo è l'articolo pilastro per la nostra serie 'responsible ai guardrails con azure ai foundry'. introduce tutti i guardrail chiave con esempi di codice autonomi, copiabili e incollabili, e si collegherà ad articoli specifici per approfondimenti ancora maggiori.

quando progetto questi sistemi su azure, non tratto la sicurezza di llm come un singolo componente. è un modello di difesa in profondità a strati. l'idea centrale è implementare una sequenza di controlli — alcuni prima che il llm venga mai chiamato, alcuni dopo che genera una risposta — per garantire che sia gli input dell'utente che gli output del modello aderiscano alle nostre politiche di sicurezza predefinite. è una pipeline di fiducia.

la nostra architettura utilizza due servizi azure chiave, composti in un ordine specifico:

1. azure ai content safety: un servizio autonomo e ad alte prestazioni che utilizziamo come prima linea di difesa. tramite contentsafetyclient.analyze_text, valuta l'input dell'utente rispetto alle categorie di danno (odio, sessuale, violenza, autolesionismo) e può generare segnali di jailbreak / attacco indiretto quando shield_prompt è abilitato — prima che il testo raggiunga il costoso llm.
2. azure openai service: il llm e i suoi filtri a livello di distribuzione. prompt shields (attacchi di prompt utente), groundedness e protected material sono integrati con questo servizio: li configuri per la distribuzione e interpreti le annotazioni restituite nella risposta dell'api azure openai insieme al completamento.

il diagramma sottostante illustra questo flusso a strati dalla richiesta dell'utente alla risposta finale e sicura dell'applicazione.

questo modello componibile, che implementeremo come middleware fastapi, è potente perché consente configurazioni specifiche dell'ambiente. il tuo ambiente dev può avere soglie permissive per i test, mentre il tuo ambiente production rimane bloccato e altamente sicuro.

prima di scrivere una riga di codice, configuriamo il nostro ambiente. questo è il toolkit standard che uso per tutti i miei progetti ia basati su azure.

• azure cli: assicurati di avere la cli installata e di essere autenticato all'abbonamento azure corretto.

az login
az account set --subscription "your-azure-subscription-id"

• terraform cli: useremo terraform per il provisioning dichiarativo dell'infrastruttura. sto usando la versione 1.5+, ma qualsiasi versione recente dovrebbe funzionare.

terraform --version

• python 3.12+: il nostro livello applicativo è costruito esclusivamente con python. insisto nell'utilizzare un ambiente virtuale per ogni progetto per gestire le dipendenze in modo pulito.

python3.12 -m venv .venv
source .venv/bin/activate
python3.12 --version

• pacchetti python richiesti: installa gli sdk azure necessari, fastapi per il nostro livello web e alcune utilità.

pip install "azure-ai-contentsafety==1.0.0b2" "azure-identity>=1.15.0" "fastapi>=0.110.0" "uvicorn[standard]>=0.29.0" "python-dotenv>=1.0.0" "openai>=1.23.0"

• variabili d'ambiente: utilizziamo variabili d'ambiente per la configurazione. crea un file .env nella directory principale del tuo progetto. defaultazurecredential le userà per lo sviluppo locale e passerà senza problemi a managed identity in azure.

# .env file
AZURE_TENANT_ID="your-tenant-id"
AZURE_CLIENT_ID="your-service-principal-app-id"
AZURE_CLIENT_SECRET="your-service-principal-password"
AZURE_SUBSCRIPTION_ID="your-azure-subscription-id"

# Endpoints from Terraform output
AZURE_CONTENT_SAFETY_ENDPOINT="https://your-content-safety-resource.cognitiveservices.azure.com/"
AZURE_OPENAI_ENDPOINT="https://your-aoai-resource.openai.azure.com/"

# Azure OpenAI Configuration
AZURE_OPENAI_API_VERSION="2024-05-01-preview"
AZURE_OPENAI_DEPLOYMENT_NAME="gpt-4o-demo"

con il nostro ambiente pronto, provisioniamo l'infrastruttura cloud di cui abbiamo bisogno.

prima di tutto: dobbiamo creare le risorse di azure. uso terraform per questo per garantire che la nostra infrastruttura sia ripetibile, versionata e documentata come codice. eseguiremo il provisioning di tutto in francecentral. questa regione è nell'elenco attuale di microsoft dove la groundedness detection è disponibile (insieme a regioni come east us e canada east); diverse regioni adiacenti all'ue non sono su quell'elenco, quindi la scelta di una regione supportata evita errori silenziosi quando si abilita la groundedness nel codice.

questa configurazione creerà: 1. un gruppo di risorse per contenere i nostri servizi. 2. un workspace di azure machine learning, che funge da nostro hub ai foundry. 3. un account autonomo azure ai content safety. 4. un account azure openai con una distribuzione gpt-4o. 5. l'assegnazione di ruolo necessaria per consentire al workspace ml di accedere al servizio openai.

ecco il file main.tf completo:

# main.tf
terraform {
  required_providers {
    azurerm = {
      source  = "hashicorp/azurerm"
      version = ">=3.90.0"
    }
  }
}

provider "azurerm" {
  features {}
}

data "azurerm_client_config" "current" {}

resource "azurerm_resource_group" "rg" {
  name     = "rg-ai-foundry-guardrails-francecentral"
  location = "francecentral"
}

# 1. AI Foundry Hub (Azure AI Workspace)
resource "azurerm_machine_learning_workspace" "ai_foundry_hub" {
  name                = "mlw-aifoundry-hub-frc"
  location            = azurerm_resource_group.rg.location
  resource_group_name = azurerm_resource_group.rg.name
  sku_name            = "Premium" # Premium SKU for advanced features

  identity {
    type = "SystemAssigned"
  }

  tags = {
    environment = "production"
    project     = "AI_Foundry_Guardrails"
  }
}

# 2. Standalone Content Safety Service
resource "azurerm_cognitive_account" "content_safety" {
  name                = "cogs-contentsafety-guardrails-frc"
  location            = azurerm_resource_group.rg.location
  resource_group_name = azurerm_resource_group.rg.name
  kind                = "ContentSafety"
  sku_name            = "S0"

  tags = {
    environment = "production"
    project     = "AI_Foundry_Guardrails"
  }
}

# 3. Azure OpenAI Service Account
resource "azurerm_cognitive_account" "openai" {
  name                = "cogs-openai-guardrails-frc"
  location            = azurerm_resource_group.rg.location
  resource_group_name = azurerm_resource_group.rg.name
  kind                = "OpenAI"
  sku_name            = "S0"
}

# 4. Azure OpenAI Deployment (e.g., GPT-4o)
resource "azurerm_cognitive_deployment" "gpt4o" {
  name                 = "gpt-4o-demo" # This must match your AZURE_OPENAI_DEPLOYMENT_NAME env var
  cognitive_account_id = azurerm_cognitive_account.openai.id
  model {
    format  = "OpenAI"
    name    = "gpt-4o"
    version = "2024-05-13"
  }
  scale {
    type = "Standard"
  }
}

# 5. RBAC: Granting the ML workspace access to OpenAI
resource "azurerm_role_assignment" "mlw_to_openai" {
  scope                = azurerm_cognitive_account.openai.id
  role_definition_name = "Cognitive Services OpenAI User"
  principal_id         = azurerm_machine_learning_workspace.ai_foundry_hub.identity[0].principal_id
}

# Outputs for our .env file
output "content_safety_endpoint" {
  description = "Endpoint for the Azure AI Content Safety service."
  value       = azurerm_cognitive_account.content_safety.endpoint
}

output "openai_endpoint" {
  description = "Endpoint for the Azure OpenAI service."
  value       = azurerm_cognitive_account.openai.endpoint
}

eseguire terraform init, terraform plan e terraform apply per creare queste risorse. una volta completato, copiare i valori di output nel file .env.

ora implementeremo ogni guardrail come componente distinto in python. questo approccio modulare rende il sistema più facile da testare, mantenere e configurare.

ora, mettiamo insieme tutto. un middleware fastapi è il luogo perfetto per orchestrare questa catena di guardrail. ci permette di intercettare ogni richiesta in entrata al nostro endpoint di chat, applicare i nostri controlli di sicurezza e modificare o bloccare la risposta prima che raggiunga l'utente.

questa implementazione definisce una classe responsibleaimiddleware che esegue la nostra logica di pre-elaborazione e post-elaborazione.

# main.py
import os
import json
from fastapi import FastAPI, Request, Response, HTTPException
from starlette.middleware.base import BaseHTTPMiddleware, RequestResponseEndpoint
from starlette.responses import JSONResponse

from azure.ai.contentsafety.models import TextCategory
from services.content_safety_service import PreemptiveContentSafety
from services.openai_service import GuardedOpenAIService

# --- App and Service Initialization ---
app = FastAPI(
    title="Secure AI Chat API",
    description="An API for chat completions with Responsible AI guardrails."
)

safety_service = PreemptiveContentSafety()
openai_service = GuardedOpenAIService()

# --- Middleware Configuration ---
# In a real app, load this from a config file or env vars
PROD_HARM_THRESHOLDS = {
    TextCategory.HATE: 2,
    TextCategory.SEXUAL: 2,
    TextCategory.VIOLENCE: 2,
    TextCategory.SELF_HARM: 4,
}

class ResponsibleAIMiddleware(BaseHTTPMiddleware):
    async def dispatch(self, request: Request, call_next: RequestResponseEndpoint) -> Response:
        if not request.url.path == "/chat/invoke":
            return await call_next(request)

        try:
            body = await request.json()
            user_prompt = body.get("prompt")
            if not user_prompt:
                return JSONResponse(status_code=400, content={"detail": "'prompt' field is required."})
        except json.JSONDecodeError:
            return JSONResponse(status_code=400, content={"detail": "Invalid JSON body."})

        # === GUARDRAIL CHAIN: PRE-PROCESSING ===
        is_safe, analysis = await safety_service.analyze_input(user_prompt, PROD_HARM_THRESHOLDS)
        if not is_safe:
            raise HTTPException(status_code=400, detail={"error": "Input rejected by content safety filter", "details": analysis})

        # If input is safe, proceed to the actual endpoint
        response = await call_next(request)

        # === GUARDRAIL CHAIN: POST-PROCESSING ===
        if response.status_code == 200:
            response_body = b''
            async for chunk in response.body_iterator:
                response_body += chunk
            response_data = json.loads(response_body)

            safety_analysis = response_data.get("safety_analysis", {})

            # Check for protected material
            if safety_analysis.get('protected_material_text') or safety_analysis.get('protected_material_code'):
                # For this example, we block. You could also replace with a citation.
                raise HTTPException(status_code=400, detail={"error": "Response blocked due to protected material detection."})

            # Check for ungroundedness
            groundedness = safety_analysis.get('groundedness', {})
            if not groundedness.get('detected', True) or groundedness.get('score', 1.0) < 0.5:
                # Append a warning instead of blocking
                response_data['content'] += "\n\n[Warning: This response may contain information not present in the source documents and should be verified.]"
                response_data['safety_analysis']['warning'] = 'low_groundedness_score'
                return JSONResponse(content=response_data)

        return response

app.add_middleware(ResponsibleAIMiddleware)

# --- API Endpoint ---
@app.post("/chat/invoke")
async def invoke_chat(request: Request):
    """
    This endpoint is protected by the ResponsibleAIMiddleware.
    It expects a body with {'prompt': '...', 'documents': ['doc1', 'doc2']}
    """
    body = await request.json()
    user_prompt = body.get("prompt")
    documents = body.get("documents", [])

    # The middleware has already validated the prompt. Now call the LLM.
    result = await openai_service.get_grounded_completion(user_prompt, documents)

    if "error" in result:
        raise HTTPException(status_code=500, detail=result)

    return JSONResponse(content=result)

con questa configurazione, ogni richiesta a /chat/invoke passa automaticamente attraverso l'intera pipeline di sicurezza. è un modo pulito, scalabile e non intrusivo per applicare le politiche di ia responsabile in tutta l'applicazione.

per le organizzazioni in europa, la domanda più pressante è: "come mi aiuta questo a rispettare l'eu ai act?" la risposta è che questi controlli tecnici si mappano direttamente a specifiche obbligazioni legali. la costruzione di questo livello di sicurezza non è solo una buona ingegneria; è un componente fondamentale della vostra strategia di conformità.

ecco come ogni guardrail si allinea agli articoli chiave della legge per i sistemi ia ad alto rischio:

la distribuzione di un llm grezzo in un ambiente di produzione, specialmente in un settore regolamentato, non è più un'opzione praticabile. i rischi di contenuti dannosi, allucinazioni catastrofiche e attacchi di iniezione di prompt sono troppo grandi, e il panorama normativo, guidato dall'eu ai act, richiede controlli concreti e dimostrabili.

abbiamo esaminato un modello completo e testato sul campo per la costruzione di una difesa a più livelli. componendo azure ai content safety per una scansione rapida degli input e sfruttando i filtri profondamente integrati di azure openai per minacce avanzate come jailbreak e non-groundedness, è possibile costruire un'applicazione ia robusta, conforme e affidabile. il modello di middleware fastapi che ho mostrato fornisce un modo flessibile e scalabile per applicare queste politiche centralmente, assicurando che il vostro llm operi in sicurezza all'interno dei guardrail che definite.

la mia raccomandazione sul campo: non cercate di fare tutto in una volta. iniziate con due guardrail: azure ai content safety su tutti gli input utente con soglie conservative e groundedness detection (rilevamento della messa a terra) su tutti gli output basati su rag. questi due controlli da soli mitigheranno oltre l'80% dei comuni problemi di sicurezza e qualità nelle distribuzioni aziendali. da lì, abilitate azure openai prompt shields sulla distribuzione e aggiungete la protected material detection (rilevamento materiale protetto) in base al profilo di rischio della vostra applicazione.

passo successivo attuabile: prendete il codice middleware fastapi da questa guida e integratelo in un nuovo ramo della vostra applicazione llm esistente. configuratelo con soglie permissive e distribuitelo in un ambiente di staging. iniziate a raccogliere i log su ciò che segnala e blocca. questi dati saranno inestimabili per la messa a punto delle vostre politiche prima di applicarle in produzione. è così che si passa dalla teoria a un sistema di sicurezza tangibile, di livello aziendale.