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à.
# Progetti (OpenAI-compatible)
L'API Amazon Bedrock Projects fornisce l'isolamento a livello di applicazione per i carichi di lavoro di IA generativa tramite API. [ OpenAI-compatible ](bedrock-mantle.md) I progetti ti consentono di organizzare e gestire le tue applicazioni di intelligenza artificiale con un migliore controllo degli accessi, monitoraggio dei costi e osservabilità in tutta l'organizzazione.
**Suggerimento**
Per le nuove applicazioni, consigliamo l'`bedrock-runtime`endpoint. Se non hai bisogno dell'API Projects, utilizza [ Inference Profiles ](inference-profiles-create.md) per l'isolamento, l'etichettatura e il monitoraggio dei costi. `bedrock-runtime`
**Nota**
I progetti possono essere utilizzati solo con modelli che utilizzano le OpenAI-compatible API sull'endpoint bedrock-mantle[. ](bedrock-mantle.md) Se stai utilizzando l'endpoint bedrock-runtime, utilizza Inference Profiles invece di tagging e osservability.
## 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 specifiche del progetto utilizzando le policy [ IAM per Amazon Bedrock Projects ](security-iam-projects.md)
+ **Monitoraggio dei costi**: monitora la spesa a livello di progetto utilizzando i tag [ AWS ](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 AWS account o organizzazioni separati, riducendo la complessità operativa e mantenendo la sicurezza e la governance.
Ogni AWS account ha un progetto predefinito a cui sono associate tutte le richieste di inferenza. Puoi creare più progetti nel tuo account utilizzando l'API Projects.
**Nota**
Il supporto per i progetti varia a seconda dell'endpoint. Sull'`bedrock-mantle`endpoint, puoi creare e gestire i tuoi progetti con l'API Projects. Sull'`bedrock-runtime`endpoint, è disponibile solo il progetto predefinito: non puoi ancora creare progetti lì. Richieste di `bedrock-runtime` risoluzione relative al progetto predefinito del tuo account, il cui ARN è. `arn:aws:bedrock:{{region}}:{{account-id}}:project/default` Il progetto predefinito non può essere taggato o eliminato, l'impostazione di conservazione dei dati viene sempre ereditata dall'account e non è mai il criterio di fatturazione: l'utilizzo `bedrock-runtime` viene attribuito al target di inferenza, esattamente come avviene oggi. Per le autorizzazioni che fanno riferimento al progetto predefinito, consulta. [Prerequisiti per l’esecuzione dell’inferenza del modello](inference-prereq.md)
## Quando usare i progetti
È necessario utilizzare l'API Projects quando è necessario:
+ **Organizza per struttura aziendale**: gestisci l'utilizzo di Bedrock in base alla tua tassonomia organizzativa, ad esempio unità aziendali, team, applicazioni o centri di costo
+ **Tieni traccia dei costi con precisione**: 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 limiti operativi e monitoraggio chiari
## Progetti e profili di inferenza
Sia l'API di 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'endpoint utilizzato. Se utilizzi OpenAI-compatible API con l'endpoint [Endpoint supportati da Amazon Bedrock](endpoints.md) bedrock-mantle, utilizza l'API Projects. Se stai usando l'[endpoint ](endpoints.md) bedrock-runtime (consigliato per le nuove applicazioni), usa Inference Profiles. L'API Chat Completions è disponibile su entrambi gli endpoint; l'API Projects è disponibile solo su. `bedrock-mantle`
| Funzionalità | API Projects | Profili di inferenza |
| --- | --- | --- |
| API supportate | OpenAI-compatible API (risposte, completamenti delle chat) | API native di Bedrock (Invoke, Converse), API (completamenti delle chat) OpenAI-compatible |
| Endpoint | bedrock-mantle.{region}.api.aws | bedrock-runtime.{region}.amazonaws.com |
| Caso d'uso | OpenAI-compatible Applicazioni che utilizzano endpoint | Applicazioni che utilizzano API Bedrock native |
| Controllo degli accessi | Il progetto come risorsa nelle politiche IAM | Politiche IAM sul profilo di inferenza ARN |
| Monitoraggio dei costi | AWS tag sui progetti | AWS tag sui profili di inferenza |
## Progetti vs. AWS account
[Gli account ](https://docs.aws.amazon.com/accounts/latest/reference/accounts-welcome.html) e [AWS le organizzazioni AWS ](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é AWS account separati fornisce:
+ **Configurazione più rapida**: crea progetti in pochi secondi tramite chiamate API.
+ **Complessità ridotta**: gestisci più carichi di lavoro senza espansione degli account
+ **Operazioni semplificate**: gestione centralizzata all'interno di un singolo account
+ **Costi generali ridotti**: non sono necessari ruoli IAM tra account o condivisione delle risorse
## Guida introduttiva ai progetti
Questa pagina illustra come creare il primo progetto, associarlo alle richieste di inferenza e gestire le risorse del progetto.
### Prerequisiti
Prima di iniziare, assicurati di avere:
+ Un AWS account con accesso ad Amazon Bedrock
+ Autorizzazioni IAM per creare e gestire progetti Bedrock
+ Python 3.7 o successivo installato
+ L'SDK OpenAI Python installato: `pip install openai boto3`
+ Una chiave [ API ](api-keys.md) per l'autenticazione Amazon Bedrock
### Passaggio 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"
```
``Sostituiscile con la tua AWS regione (ad esempio, us-east-1, us-west-2).
**Nota**
Amazon Bedrock offre [ due tipi di chiavi: a breve termine e a lungo termine. ](bedrock/latest/userguide/api-keys-how.html) Sebbene tu possa 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 policy predefinita associata alle chiavi a lungo termine ti consente solo di ottenere ed elencare i progetti, ma non di archiviarli create/update. Se desideri che la tua chiave a lungo termine gestisca 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"
```
### Fase 3: Crea il tuo primo progetto
Crea un progetto utilizzando l'API Create Project con tag per il monitoraggio e l'osservabilità dei costi. 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 della policy IAM.
+ I tag possono essere specificati durante la creazione del progetto e vengono restituiti in tutte le risposte del progetto.
### Fase 4: Associa le richieste di inferenza al tuo progetto
Per associare il 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 il corretto isolamento, il monitoraggio dei costi e il controllo degli accessi.
### Fase 5: Verifica la 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 politiche IAM per limitare l'accesso al progetto
+ **Imposta il monitoraggio dei costi**: aggiungi AWS tag 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/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 riflettano la tua struttura organizzativa:
+ **Per applicazione**:, CustomerChatbot-Prod InternalSearch-Dev
+ **Per squadra**: TeamAlpha-Production, DataScience-Experiments
+ **Per ambiente**: Production-WebApp, Staging-MobileApp
+ **Per centro di costo**: CostCenter-2152-Production
### 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, ad esempio 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 del progetto
Aggiungere nuovi tag o aggiornare 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 con le relative 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 contemporaneamente. È necessario specificare esplicitamente quali tag aggiungere e quali rimuovere.
**Gestione degli errori**: implementa una 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 e le metriche storici rimangono accessibili fino a 30 giorni.
### Utilizzo di progetti con API diverse
------
#### [ 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 gli ambienti di sviluppo, staging e produzione.
+ **Isolamento degli esperimenti**: crea progetti dedicati per esperimenti e prove di concetti.
#### 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 organizzative
+ **Scopo del progetto del documento**: includi descrizioni chiare
+ **Audit regolari**: esamina e archivia periodicamente i progetti inutilizzati
+ **Monitora l'utilizzo**: tieni traccia delle metriche del progetto per identificare le opportunità di ottimizzazione