Come configurare protezioni e controlli in Microsoft Foundry

Informazioni su come creare, configurare e gestire limiti di sicurezza per le distribuzioni e gli agenti del modello in Microsoft Foundry usando il portale Foundry o l'API REST.

Per informazioni sui concetti, sui rischi e sui punti di intervento, vedere Cenni preliminari sui guardrail e sui controlli.

Prerequisiti

• Sottoscrizione Azure. Crearne uno gratuitamente.
• Progetto Microsoft Foundry.
• Almeno una distribuzione modello nel progetto.
• Proprietario dell'Account Azure AI o ruolo superiore nella risorsa Azure AI.

Disponibilità

Vedere disponibilità dell'area.

Creare un guardrail in Foundry

1. Vai a Foundry e accedi al tuo progetto.
2. Selezionare Compila nel menu in alto a destra.
3. Selezionare la pagina Guardrails nella barra di navigazione a sinistra.
4. Selezionare Crea guardrail in alto a destra. La protezione guidata viene visualizzata al passaggio 1: Aggiungere controlli.

Aggiungere controlli a un guardrail

I controlli predefiniti vengono visualizzati nel riquadro destro quando si crea un nuovo guardrail.

1. Selezionare un rischio dal menu a discesa.

2. Scegliere i punti di intervento e le azioni: vengono visualizzati i punti di intervento e le azioni consigliati per tale rischio. Selezionare uno o più punti di intervento e un'azione per configurare il controllo.

   Nota

   Alcuni punti di intervento non saranno disponibili per un rischio se questo è inapplicabile a quel punto di intervento. Ad esempio, per definizione, gli attacchi di input utente sono contenuti dannosi aggiunti all'input dell'utente. Quindi, questo rischio può essere analizzato solo a quel punto di intervento.

3. Selezionare Aggiungi controllo. Il controllo viene aggiunto alla tabella a destra.

Eliminare i controlli da una barriera di sicurezza

Per eliminare un controllo:

1. Selezionare il controllo da rimuovere.
2. Selezionare Elimina.

Modificare i controlli nel guardrail

Esistono due modi per modificare un controllo: eliminarlo e aggiungerne uno nuovo oppure eseguire l'override di un controllo esistente. Quest'ultimo è l'unico modo per modificare un controllo che non può essere eliminato, ad esempio Violenza, Odio, Sesso e Autolesionismo controlli su input e output degli utenti.

Per modificare un controllo eseguendo l'override:

1. Selezionare il medesimo rischio del controllo da modificare.
2. Modificare la configurazione del controllo o i punti di intervento e l'azione in base alle esigenze.
3. Selezionare Aggiungi controllo.
4. Un popup chiede conferma per eseguire l'override del controllo esistente. Selezionare Conferma.

Assegnare un guardrail agli agenti e ai modelli

Dopo l'aggiunta, la modifica e/o l'eliminazione di controlli in base alle esigenze:

1. Selezionare Avanti per procedere al passaggio 2: assegnazione di una protezione agli agenti e/o ai modelli.
2. Selezionare Aggiungi agenti e/o Aggiungi modelli per visualizzare un elenco di agenti e modelli in questo progetto.
3. Selezionare modelli o agenti. Gli agenti e i modelli assegnati in precedenza possono anche essere deselezionati per rimuovere questa protezione e riassegnare il Microsoft Default.
4. Selezionare Salva per confermare. Viene visualizzata una notifica di esito positivo.

Rivedere e assegnare un nome a Guardrail

1. Selezionare Avanti per procedere al Passaggio 3: Revisione.
2. Esamina i controlli aggiunti a questa barriera protettiva e i modelli e/o l'agente a cui è assegnata.
3. Assegnare un nome al guardrail o lasciare il nome assegnato automaticamente.
4. Selezionare Crea. La protezione viene visualizzata nell'elenco nella pagina Protezioni e viene applicata ai modelli e agli agenti selezionati.

Modificare una protezione esistente

1. Selezionare Compila nel menu in alto a destra.

2. Selezionare la pagina Guardrails nella barra di navigazione a sinistra.

3. Trova il guardrail nell'elenco dei guardrail. Selezionare direttamente il nome oppure selezionarne la riga e quindi selezionare Modifica nel riquadro dei dettagli.

   Nota

   Microsoft Non è possibile modificare le protezioni predefinite, ad esempio Default.V2.

4. Seguire le stesse istruzioni riportate in Creare una protezione per modificare, aggiungere o rimuovere controlli; assegnare o riassegnare agenti e/o modelli; e rinominare il guardrail, in base alle esigenze.

Assegnare un guardrail

Esistono due percorsi per assegnare una protezione a un modello o a un agente:

Opzione 1: Modificare la barriera di sicurezza

1. Selezionare Compila nel menu in alto a destra.
2. Selezionare la pagina Guardrails nella barra di navigazione a sinistra.
3. Trova il guardrail nell'elenco dei guardrail. Selezionare direttamente il nome oppure selezionarne la riga e quindi selezionare Modifica nel riquadro dei dettagli.
4. Selezionare Avanti nel passaggio 1: Aggiungere controlli per passare al passaggio di assegnazione.
5. Selezionare Aggiungi agenti o Aggiungi modelli e selezionare e deselezionare modelli e/o agenti in base alle esigenze per aggiornare l'assegnazione della protezione.

Opzione 2: Modificare il modello o l'agente

1. Selezionare Compila nel menu in alto a destra.
2. Selezionare Agenti o Modelli nella barra di navigazione a sinistra.
3. Selezionare l'agente o il modello da aggiornare.
4. Nel pannello sinistro di Agent Playground o Chat Playground viene visualizzata una sezione per Guardrails .
5. Selezionare Gestisci nella parte inferiore della sezione Guardrails.
6. Selezionare Assegna un nuovo guardrail.
7. Esplora i guardrail disponibili in questo progetto.
8. Selezionare il parapetto desiderato dall'elenco a sinistra della finestra popup.
9. Selezionare Assegna per aggiornare l'assegnazione della protezione dell'agente o del modello. Il nuovo guardrail diventa effettivo immediatamente.

Eliminare un guardrail

Per eliminare un guardrail senza modelli o agenti assegnati

1. Selezionare Compila nel menu in alto a destra.
2. Selezionare la pagina Guardrails nella barra di navigazione a sinistra.
3. Trovare il guardrail nell'elenco dei guardrail e selezionarne la riga.
4. Viene visualizzato un pannello a destra. Selezionare Elimina nella parte superiore del pannello.

Per eliminare un guardrail con modelli o agenti assegnati

1. Riassegnare i modelli e/o gli agenti a un guardrail diverso o rimuoverli da questa protezione per riassegnarli ai Microsoft Guardrail predefiniti.
2. Seguire istruzioni per eliminare un guardrail senza modelli o agenti assegnati.

Test guardrail

Per testare il comportamento di una particolare guardrail:

1. Selezionare Compila nel menu in alto a destra.

2. Selezionare la pagina Guardrails nella barra di navigazione a sinistra.

3. Trovare il guardrail nell'elenco dei guardrail e selezionarne la riga.

4. Viene visualizzato un pannello a destra. Seleziona Prova in Playground nella parte superiore del pannello.

   Nota

   Se questo pulsante non viene visualizzato, assegnare prima questa protezione a un modello o a un agente. L'assegnazione di un guardrail modifica immediatamente il comportamento di sicurezza e protezione, quindi utilizzare un modello o agente di non produzione per i test.

5. Nel playground, inviare query al modello o all'agente.

6. Quando viene attivato un controllo con "Annotazioni e blocchi" come azione, viene visualizzato un messaggio nella chat con i dettagli sul rischio rilevato e in quale punto di intervento.

Configurare protezioni con l'API REST

Nell'API REST di Azure AI Services, una protezione, rappresentata come una politica RAI, è un oggetto a livello di risorsa in Azure Resource Manager.

Creare o aggiornare un corrimano

Utilizzare l'operazione Criteri RAI - Crea o Aggiorna per creare o aggiornare una barriera. Specificare i controlli (regole di filtro del contenuto) nel corpo della richiesta, inclusa la categoria di rischio, il livello di gravità e se bloccare o annotare.

Assegnare una protezione a una distribuzione modello

Impostare la proprietà raiPolicyName su una distribuzione per assegnare una protezione. Usare l'operazione Distribuzioni - Creare o aggiornare e includere il nome della protezione nelle proprietà della distribuzione.

Usare le annotazioni

Foundry fornisce annotazioni che aiutano a comprendere i risultati della protezione per le richieste. Le annotazioni possono essere abilitate anche per i filtri e i livelli di gravità che sono stati disabilitati dal blocco del contenuto.

Annotazioni di barriere standard

Quando le annotazioni sono abilitate, le informazioni seguenti vengono restituite tramite l'API per le categorie odio, sesso, violenza e autolesionismo:

• Categoria di rischio (odio, sesso, violenza, self_harm)
• Livello di gravità (sicuro, basso, medio o alto) all'interno di ogni categoria di contenuto
• Stato filtro (true o false)

Annotazioni del modello facoltative

Le annotazioni del modello facoltative possono essere impostate sulla modalità di annotazione (restituisce informazioni quando il contenuto viene contrassegnato, ma non filtrato) o la modalità filtro (restituisce informazioni quando il contenuto viene contrassegnato e filtrato).

Compatibilità delle versioni dell'API

La tabella seguente mostra la disponibilità della modalità annotazione in ogni versione dell'API:

¹ Non disponibile in scenari non di streaming; disponibile solo per gli scenari di streaming.

Scelta di una versione dell'API

• Per le distribuzioni di produzione: usare la versione ga più recente (2024-02-01) per la stabilità e il supporto.
• Per il rilevamento delle informazioni personali: usare 2025-01-01-preview o una versione successiva.
• Per il rilevamento della fondatezza: usare 2025-01-01-preview o successive.
• Per il rilevamento degli attacchi indiretti: usare 2024-04-01-preview o versione successiva.

Le versioni dell'API di anteprima includono le funzionalità più recenti, ma potrebbero avere modifiche di rilievo. Testare sempre le funzionalità di anteprima in ambienti non di produzione prima della distribuzione.

Esempi di codice

I frammenti di codice seguenti illustrano come visualizzare le annotazioni di protezione in linguaggi di programmazione diversi.

Installare le dipendenze

Prima di eseguire gli esempi di codice, installare le librerie necessarie:

pip install openai>=1.0.0

npm install openai@^4.0.0

Visualizzare le annotazioni

# os.getenv() for the endpoint and key assumes that you are using environment variables.

import os
from openai import AzureOpenAI

client = AzureOpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),  
    api_version="2024-03-01-preview",
    azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT") 
)

response = client.completions.create(
    model="gpt-35-turbo-instruct", # model = "deployment_name".
    prompt="{Example prompt where a severity level of low is detected}" 
    # Content that is detected at severity level medium or high is filtered, 
    # while content detected at severity level low isn't filtered by the content filters.
)

print(response.model_dump_json(indent=2))

const { OpenAI } = require('openai');

const client = new OpenAI({
  apiKey: process.env.AZURE_OPENAI_API_KEY,
  baseURL: `${process.env.AZURE_OPENAI_ENDPOINT}/openai/deployments/gpt-35-turbo-instruct`,
  defaultQuery: { 'api-version': '2024-03-01-preview' },
  defaultHeaders: {
    'api-key': process.env.AZURE_OPENAI_API_KEY,
  },
});

async function main() {
  const completion = await client.completions.create({
    model: '',
    prompt: 'Example prompt where a severity level of low is detected',
  });

  console.log(JSON.stringify(completion, null, 2));
}

main();

Output di esempio

{
  "choices": [
    {
      "content_filter_results": {
        "hate": {
          "filtered": false,
          "severity": "safe"
        },
        "protected_material_code": {
          "citation": {
            "URL": "https://github.com/username/repository-name/path/to/file-example.txt",
            "license": "EXAMPLE-LICENSE"
          },
          "detected": true,
          "filtered": false
        },
        "protected_material_text": {
          "detected": false,
          "filtered": false
        },
        "self_harm": {
          "filtered": false,
          "severity": "safe"
        },
        "sexual": {
          "filtered": false,
          "severity": "safe"
        },
        "violence": {
          "filtered": false,
          "severity": "safe"
        }
      },
      "finish_reason": "stop",
      "index": 0,
      "message": {
        "content": "Example model response will be returned",
        "role": "assistant"
      }
    }
  ],
  "created": 1699386280,
  "id": "chatcmpl-8IMI4HzcmcK6I77vpOJCPt0Vcf8zJ",
  "model": "gpt-35-turbo-instruct",
  "object": "text.completion",
  "usage": {
    "completion_tokens": 40,
    "prompt_tokens": 11,
    "total_tokens": 417
  },
  "prompt_filter_results": [
    {
      "content_filter_results": {
        "hate": {
          "filtered": false,
          "severity": "safe"
        },
        "jailbreak": {
          "detected": false,
          "filtered": false
        },
        "profanity": {
          "detected": false,
          "filtered": false
        },
        "self_harm": {
          "filtered": false,
          "severity": "safe"
        },
        "sexual": {
          "filtered": false,
          "severity": "safe"
        },
        "violence": {
          "filtered": false,
          "severity": "safe"
        }
      },
      "prompt_index": 0
    }
  ]
}

Per informazioni dettagliate sugli endpoint dell'API REST di inferenza per Azure OpenAI e su come creare chat e completamenti, seguire le indicazioni di riferimento dell'API REST di Azure OpenAI. Le annotazioni vengono restituite per tutti gli scenari quando si usa qualsiasi versione dell'API di anteprima a partire dalla versione 2023-06-01-preview, nonché dall'API GA versione 2024-02-01.

Incorporamento di documenti nei prompt

Le barriere offrono prestazioni migliori quando possono distinguere i vari elementi della richiesta, come l'input del sistema, l'input dell'utente e l'output dell'assistente AI. Per le funzionalità di rilevamento avanzate, i prompt devono essere formattati in base ai metodi consigliati seguenti.

Comportamento predefinito nell'API dei completamenti chat

L'API di completamento della chat è strutturata per definizione. Gli input sono costituiti da un elenco di messaggi, ognuno con un ruolo assegnato.

Il sistema di sicurezza analizza questo formato strutturato e applica il comportamento seguente:

Nel contenuto "utente" più recente vengono rilevate le categorie di rischi seguenti:

• Odio
• Sessuale
• Violenza
• Autolesionismo
• Protezioni dei prompt (facoltativo)

Matrice di messaggi di esempio:

[
  {"role": "system", "content": "Provide some context and/or instructions to the model."},
  {"role": "user", "content": "Example question goes here."},
  {"role": "assistant", "content": "Example answer goes here."},
  {"role": "user", "content": "First question/message for the model to actually respond to."}
]

Incorporamento di documenti nel prompt

Oltre al rilevamento degli ultimi contenuti utente, Azure OpenAI supporta anche il rilevamento di rischi specifici all'interno dei documenti contestuali tramite Protezioni richieste - Rilevamento di attacchi prompt indiretti e Rilevamento della fondatezza. È necessario identificare le parti dell'input che sono un documento (ad esempio, sito Web recuperato, posta elettronica e così via) con il delimitatore di documento seguente:

""" <documents> *insert your document content here* </documents> """

Quando si esegue questa operazione, sono disponibili le opzioni seguenti per il rilevamento nei documenti contrassegnati:

• Attacchi indiretti (facoltativo)
• Rilevamento fondatezza

Matrice di messaggi di completamento della chat di esempio:

[
  {"role": "system", "content": "Provide some context and/or instructions to the model."},
  {"role": "user", "content": "First question/message for the model to actually respond to, including document context. \"\"\" <documents>\n*insert your document content here*\n</documents> \"\"\""}
]

Escape JSON

Quando si contrassegnano documenti non controllati per il rilevamento, il contenuto del documento deve essere preceduto da un escape JSON per garantire la corretta analisi da parte del sistema di sicurezza dell'intelligenza artificiale Azure.

Ad esempio, vedere il corpo del messaggio di posta elettronica seguente:

Hello José,

I hope this email finds you well today.

Con l'escape JSON, si leggerebbe:

Hello Jos\u00E9,\nI hope this email finds you well today.

Il testo preceduto da escape in un contesto di completamento della chat sarà:

[
  {"role": "system", "content": "Provide some context and/or instructions to the model, including document context. \"\"\" <documents>\n Hello Jos\\u00E9,\\nI hope this email finds you well today. \n</documents> \"\"\""},
  {"role": "user", "content": "First question/message for the model to respond to"}
]

Specificare la configurazione guardrail in fase di richiesta

Oltre alla protezione a livello di distribuzione del modello, è possibile specificare la protezione personalizzata in fase di richiesta per ogni chiamata API usando un'intestazione di richiesta.

curl --request POST \
    --url 'URL' \
    --header 'Content-Type: application/json' \
    --header 'api-key: API_KEY' \
    --header 'x-policy-id: CUSTOM_CONTENT_FILTER_NAME' \
    --data '{
        "messages": [
            {
                "role": "system",
                "content": "You are a creative assistant."
            },
            {
                "role": "user",
                "content": "Write a poem about the beauty of nature."
            }
        ]
    }'

La configurazione delle protezioni a livello di richiesta eseguirà l'override della configurazione a livello di distribuzione per la chiamata API specifica.

Se viene specificata una configurazione che non esiste, viene restituito il messaggio di errore seguente:

{
    "error": {
        "code": "InvalidContentFilterPolicy",
        "message": "Your request contains invalid content filter policy. Please provide a valid policy."
    }
}

Procedure consigliate

Seguire queste procedure quando si configurano protezioni:

• Test prima della produzione: usare il playground per testare il comportamento della protezione prima di applicare modifiche alle distribuzioni di produzione.
• Iniziare con restrizioni, quindi rilassarsi: iniziare con soglie di gravità più elevate e regolare verso il basso solo dopo aver confermato il comportamento accettabile.
• Red teaming della configurazione: eseguire i test di red teaming e stress ed effettuare l'analisi per identificare potenziali danni specifici per il modello, l'applicazione e lo scenario di distribuzione.
• Misura dopo le modifiche: dopo l'implementazione o l'aggiornamento delle protezioni, ripetere il processo di misurazione per verificare l'efficacia.
• Monitorare l'impatto sulle prestazioni: l'elaborazione "guardrail" aggiunge circa 50-100 ms di latenza per punto di intervento. Per gli scenari con velocità effettiva elevata, iniziare con i controlli essenziali e monitorare solo le metriche di latenza.

Per indicazioni complete sull'IA responsabile, vedere Panoramica dell'IA responsabile.

Risoluzione dei problemi

Passaggi successivi

• Panoramica delle protezioni e dei controlli
• Punti di intervento e controlli
• Filtro del contenuto
• Configurare i filtri di contenuto per Azure OpenAI