Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.
# API dei progetti
[L'API Amazon Bedrock Projects fornisce l'isolamento a livello di applicazione per i carichi di lavoro di intelligenza artificiale generativa utilizzando la compatibilità con OpenAI. APIs](bedrock-mantle.md) I progetti ti consentono di organizzare e gestire le tue applicazioni AI con un migliore controllo degli accessi, il monitoraggio dei costi e l'osservabilità in tutta l'organizzazione.
**Nota**
[I progetti possono essere utilizzati solo con modelli che utilizzano la compatibilità con OpenAI sull'endpoint APIs bedrock-mantle.](bedrock-mantle.md) Se stai utilizzando l'endpoint bedrock-runtime, utilizza i profili di inferenza anziché i tag e l'osservabilità.
## Che cos'è un progetto?
Un progetto è un limite logico utilizzato per isolare carichi di lavoro come applicazioni, ambienti o esperimenti all'interno di Amazon Bedrock. I progetti forniscono:
+ **Isolamento degli accessi**: controlla chi può accedere a risorse di progetto specifiche utilizzando le [policy di AWS Identity and Access Management (IAM)](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html)
+ **Monitoraggio dei costi**: monitora la spesa a livello di progetto utilizzando [tag AWS](https://docs.aws.amazon.com/whitepapers/latest/tagging-best-practices/what-are-tags.html) e [AWS Cost Explorer](https://docs.aws.amazon.com/cost-management/latest/userguide/ce-what-is.html)
I progetti consentono di gestire più carichi di lavoro di intelligenza artificiale generativa in produzione senza creare account o organizzazioni AWS separati, riducendo la complessità operativa e mantenendo la sicurezza e la governance.
Ogni account AWS ha un progetto predefinito a cui sono associate tutte le richieste di inferenza. Puoi creare più progetti nel tuo account utilizzando l'API Projects.
## Quando usare i progetti
È necessario utilizzare l'API Projects quando è necessario:
+ **Organizza per struttura aziendale**: gestisci l'utilizzo di Bedrock in base alla tassonomia organizzativa, ad esempio unità aziendali, team, applicazioni o centri di costo
+ **Isola i dati sensibili**: assicurati che i prompt, le risposte e i dati contestuali di un'applicazione non siano accessibili ad altre applicazioni
+ **Tieni traccia dei costi in modo accurato**: monitora e alloca la spesa per l'IA a team, progetti o ambienti specifici
+ **Applica le politiche di accesso**: applica autorizzazioni IAM granulari per controllare chi può accedere a carichi di lavoro AI specifici
+ **Scala i carichi di lavoro di produzione**: esegui più applicazioni di produzione con confini operativi e monitoraggio chiari
## Progetti e profili di inferenza
Sia l'API Projects che [i profili di inferenza](inference-profiles-create.md) forniscono funzionalità di isolamento, etichettatura e controllo degli accessi in Amazon Bedrock, ma differiscono in base all'API utilizzata. Se utilizzi OpenAI compatibile APIs con l'endpoint [bedrock-mantle, che utilizza il motore di inferenza Mantle](endpoints.md), usa l'API Projects. [Se utilizzi Invoke o Converse con l'endpoint bedrock-runtime, usa Inference Profiles. APIs ](endpoints.md) Sebbene tu possa utilizzare l'API Chat Completions con endpoint bedrock-mantle o bedrock-runtime, ti consigliamo di utilizzare l'endpoint Mantle.
| Funzionalità | API dei progetti | Profili di inferenza |
| --- | --- | --- |
| Supportati APIs | Compatibile con OpenAI APIs (risposte, completamenti chat) | Bedrock nativo APIs (Invoke, Converse), API compatibile con OpenAI (completamento della chat) |
| Endpoint | bedrock-mantle.\$1region\$1.api.aws | bedrock-runtime.\$1region\$1.amazonaws.com |
| Caso d'uso | Applicazioni che utilizzano endpoint compatibili con OpenAI | Applicazioni che utilizzano Bedrock nativo APIs |
| Controllo degli accessi | Il progetto come risorsa nelle politiche IAM | Politiche IAM sul profilo di inferenza ARN |
| Monitoraggio dei costi | Tag AWS sui progetti | Tag AWS sui profili di inferenza |
## Progetti e account AWS
[Gli account AWS](https://docs.aws.amazon.com/accounts/latest/reference/accounts-welcome.html) [e AWS Organizations](https://docs.aws.amazon.com/controltower/latest/userguide/organizations.html) rappresentano i limiti di fatturazione e proprietà a livello di infrastruttura. I progetti rappresentano i limiti del carico di lavoro e delle applicazioni all'interno di un singolo account.
L'utilizzo di Projects anziché account AWS separati offre:
+ **Configurazione più rapida**: crea progetti in pochi secondi tramite chiamate API
+ **Complessità ridotta**: gestisci più carichi di lavoro senza la crescita incontrollata degli account
+ **Operazioni semplificate: gestione** centralizzata all'interno di un unico account
+ **Sovraccarico inferiore**: non sono necessari ruoli IAM tra account o condivisione delle risorse
## Guida introduttiva a Projects
Questa pagina illustra come creare il primo progetto, associarlo a richieste di inferenza e gestire le risorse del progetto.
### Prerequisiti
Prima di iniziare, assicurati di disporre dei seguenti elementi:
+ Un account AWS con accesso ad Amazon Bedrock
+ Autorizzazioni IAM per creare e gestire progetti Bedrock
+ Python 3.7 o successivo installato
+ L'SDK Python di OpenAI è installato: `pip install openai boto3`
+ Una [chiave API](api-keys.md) per l'autenticazione Amazon Bedrock
### Fase 1: configura il tuo ambiente
Configura le variabili di ambiente con le tue credenziali Amazon Bedrock:
```
export OPENAI_API_KEY=""
export OPENAI_BASE_URL="https://bedrock-mantle..api.aws/v1"
```
Sostituisci `` con la tua regione AWS (ad es. us-east-1, us-west-2).
**Nota**
Amazon Bedrock offre [due tipi di chiavi](https://docs.aws.amazon.com/bedrock/latest/userguide/api-keys-how.html): a breve e a lungo termine. Sebbene sia possibile utilizzare chiavi API a lungo termine per esplorare Amazon Bedrock, consigliamo chiavi a breve termine per applicazioni con requisiti di sicurezza più elevati. Se utilizzi chiavi a lungo termine con Projects, tieni presente che la politica predefinita associata alle chiavi a lungo termine ti consente solo di ottenere ed elencare i progetti, ma non create/update/archive quelli. Se desideri utilizzare la tua chiave a lungo termine per gestire i progetti, dovrai assegnare politiche IAM aggiuntive alle tue chiavi per abilitare queste operazioni.
### Fase 2: Scopri i modelli disponibili
Usa l'`list()`API per recuperare un elenco di modelli compatibili con l'API Projects:
```
curl -X GET $OPENAI_BASE_URL/models \
-H "Authorization: Bearer $OPENAI_API_KEY"
```
### Passaggio 3: crea il tuo primo progetto
Crea un progetto utilizzando l'API Create Project con tag per il monitoraggio dei costi e l'osservabilità. Nota che al momento solo CURL è supportato nell'SDK.
```
curl -X POST $OPENAI_BASE_URL/organization/projects \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Project ABC",
"tags": {
"Project": "CustomerChatbot",
"Environment": "Production",
"Owner": "TeamAlpha",
"CostCenter": "21524"
}
}' -v
```
Risposta:
```
{
"arn": "arn:aws:bedrock-mantle:ap-northeast-1:673693429514:project/proj_5d5ykleja6cwpirysbb7",
"created_at": 1772135628,
"id": "proj_5d5ykleja6cwpirysbb7",
"name": "Project ABC",
"object": "organization.project",
"status": "active",
"tags": {
"Owner": "TeamAlpha",
"Project": "CustomerChatbot",
"Environment": "Production",
"CostCenter": "21524"
}
}
```
**Note importanti:**
+ Il parametro geografico nella specifica dell'API OpenAI viene ignorato da Amazon Bedrock.
+ La regione è determinata dalla configurazione dell'endpoint.
+ Il campo arn è specifico di Amazon Bedrock e fornisce l'ARN per l'allegato alla policy IAM.
+ I tag possono essere specificati durante la creazione del progetto e vengono restituiti in tutte le risposte del progetto.
### Fase 4: Associare le richieste di inferenza al progetto
Per associare il tuo progetto alle richieste di inferenza, fornisci l'ID del progetto durante la creazione del client:
------
#### [ cURL ]
```
curl -X POST $OPENAI_BASE_URL/responses \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-H "OpenAI-Project: proj_5d5ykleja6cwpirysbb7" \
-d '{
"model": "openai.gpt-oss-120b",
"input": "Explain the benefits of using projects in Amazon Bedrock"
}'
```
------
#### [ Python ]
```
from openai import OpenAI
client = OpenAI(project="proj_5d5ykleja6cwpirysbb7")
```
------
Tutte le richieste di inferenza effettuate con questo client verranno associate al progetto specificato, garantendo un isolamento adeguato, il monitoraggio dei costi e il controllo degli accessi.
### Fase 5: Verifica della configurazione del progetto
Elenca tutti i progetti per verificare che il progetto sia stato creato correttamente:
```
curl -X GET $OPENAI_BASE_URL/organization/projects \
-H "Authorization: Bearer $OPENAI_API_KEY"
```
Risposta:
```
{
"data": [
{
"arn": "arn:aws:bedrock-mantle:ap-northeast-1:673693429514:project/default",
"created_at": 1764460800,
"id": "default",
"name": "default",
"object": "organization.project",
"status": "active",
"tags": {}
},
{
"arn": "arn:aws:bedrock-mantle:ap-northeast-1:673693429514:project/proj_2z766pfxmkij5vwubv75",
"created_at": 1771823259,
"id": "proj_2z766pfxmkij5vwubv75",
"name": "Project ABC",
"object": "organization.project",
"status": "active",
"tags": {}
}
],
"first_id": "default",
"has_more": false,
"last_id": "proj_znaruqn723npmjqnxqfd",
"object": "list"
}
```
### Fasi successive
Ora che hai creato il tuo primo progetto, puoi:
+ **Configurare il controllo degli accessi**: allega le politiche IAM per limitare l'accesso al progetto
+ **Imposta il monitoraggio dei costi**: aggiungi tag AWS per l'allocazione dei costi
+ **Abilita il monitoraggio**: configura CloudWatch metriche e allarmi
+ **Crea progetti aggiuntivi**: organizza i carichi di lavoro per team, ambiente o applicazione
## Utilizzo dei progetti
Questa pagina fornisce informazioni dettagliate sulla gestione dei progetti durante il loro ciclo di vita.
### Creazione di progetti
#### Creazione di progetti di base
Crea un progetto con nome, descrizione e tag:
```
curl -X POST $OPENAI_BASE_URL/v1/organization/projects \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Development Environment",
"tags": {
"Project": "InternalTools",
"Environment": "Development",
"Owner": "TeamAlpha",
"CostCenter": "30156"
}
}'
```
Puoi avere fino a 1000 progetti per account.
#### Convenzioni di denominazione consigliate
Usa nomi chiari e descrittivi che rispecchino la tua struttura organizzativa:
+ **Per applicazione**: CustomerChatbot -Prod, -Dev InternalSearch
+ **Per squadra**: TeamAlpha -Production, -Experiments DataScience
+ **Per ambiente**: Produzione-WebApp, Allestimento- MobileApp
+ Per **centro di costo: -2152-Produzione** CostCenter
### Elenco dei progetti
#### Elenca tutti i progetti
Recupera tutti i progetti nel tuo account:
```
curl -X GET $OPENAI_BASE_URL/organization/projects \
-H "Authorization: Bearer $OPENAI_API_KEY"
```
### Recupero dei dettagli del progetto
Ottieni informazioni dettagliate su un progetto specifico:
```
curl -X GET $OPENAI_BASE_URL/organization/projects/proj_5d5ykleja6cwpirysbb7 \
-H "Authorization: Bearer $OPENAI_API_KEY"
```
### Aggiornamento dei progetti
Modifica le proprietà del progetto come il nome:
```
curl -X POST $OPENAI_BASE_URL/organization/projects/proj_5d5ykleja6cwpirysbb7 \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Production Chatbot v2"
}'
```
### Gestione dei tag di progetto
Aggiungi nuovi tag o aggiorna i valori dei tag esistenti:
```
curl -X POST $OPENAI_BASE_URL/organization/projects/proj_5d5ykleja6cwpirysbb7 \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"add_tags": {
"Application": "WebApp",
"Version": "2.0",
"Team": "Engineering"
}
}'
```
Rimuovi tag specifici tramite le loro chiavi:
```
curl -X POST $OPENAI_BASE_URL/organization/projects/proj_5d5ykleja6cwpirysbb7 \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"remove_tag_keys": ["Version", "OldTagKey"]
}'
```
**Note importanti**
**Nessuna sostituzione completa**: non è possibile sostituire l'intero set di tag in una sola volta. È necessario specificare in modo esplicito quali tag aggiungere e quali rimuovere.
**Gestione degli errori**: implementa la corretta gestione e verifica degli errori
### Archiviazione dei progetti
Archivia i progetti che non sono più in uso:
```
curl -X POST $OPENAI_BASE_URL/organization/projects/proj_abc123/archive \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json"
```
**Importante**
I progetti archiviati non possono essere utilizzati per nuove richieste di inferenza, ma i dati storici e le metriche rimangono accessibili per un massimo di 30 giorni.
### Utilizzo di progetti con caratteristiche diverse APIs
------
#### [ Responses API ]
```
from openai import OpenAI
client = OpenAI(project="proj_abc123")
response = client.responses.create(
model="openai.gpt-oss-120b",
input="What are the key features of Amazon Bedrock?"
)
print(response)
```
------
#### [ Chat Completions API ]
```
from openai import OpenAI
client = OpenAI(project="proj_abc123")
response = client.chat.completions.create(
model="openai.gpt-oss-120b",
messages=[
{"role": "user", "content": "Explain how projects improve security"}
]
)
print(response.choices[0].message.content)
```
------
### Best practice
#### Struttura del progetto consigliata
**Un progetto per applicazione**: crea progetti separati per ogni applicazione o servizio distinto.
```
├── CustomerChatbot-Production
├── CustomerChatbot-Staging
├── CustomerChatbot-Development
├── InternalSearch-Production
└── InternalSearch-Development
```
+ **Ambienti separati**: utilizza progetti diversi per ambienti di sviluppo, allestimento e produzione.
+ **Isolamento sperimentale**: crea progetti dedicati per esperimenti e proof-of-concepts.
#### Gestione del ciclo di vita del progetto
+ **Crea progetti in anticipo**: configura i progetti prima di distribuire le applicazioni
+ **Usa una denominazione coerente: segui le convenzioni di denominazione** delle organizzazioni
+ **Scopo del progetto del documento: includi** descrizioni chiare
+ **Audit regolari**: rivedi e archivia periodicamente i progetti non utilizzati
+ **Monitora l'utilizzo: monitora** le metriche del progetto per identificare le opportunità di ottimizzazione