As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.
# API de projetos
[A API Amazon Bedrock Projects fornece isolamento em nível de aplicativo para suas cargas de trabalho generativas de IA usando a API compatível com OpenAI. APIs](bedrock-mantle.md) Os projetos permitem que você organize e gerencie seus aplicativos de IA com controle de acesso aprimorado, controle de custos e observabilidade em toda a organização.
**nota**
[Os projetos só podem ser usados com modelos que usam o compatível com OpenAI em APIs relação ao endpoint Bedrock-mantle.](bedrock-mantle.md) Se você estiver usando o endpoint bedrock-runtime, use Perfis de inferência em vez de marcação e observabilidade.
## O que é um projeto?
Um projeto é um limite lógico usado para isolar cargas de trabalho, como aplicativos, ambientes ou experimentos no Amazon Bedrock. Os projetos fornecem:
+ **Isolamento de acesso**: controle quem pode acessar recursos específicos do projeto usando [as políticas do AWS Identity and Access Management (IAM)](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html)
+ **Monitoramento de custos**: acompanhe os gastos no nível do projeto usando [tags da AWS](https://docs.aws.amazon.com/whitepapers/latest/tagging-best-practices/what-are-tags.html) e o [AWS Cost Explorer](https://docs.aws.amazon.com/cost-management/latest/userguide/ce-what-is.html)
Os projetos permitem que você gerencie várias cargas de trabalho de IA generativas na produção sem criar contas ou organizações separadas da AWS, reduzindo a complexidade operacional e mantendo a segurança e a governança.
Cada conta da AWS tem um projeto padrão ao qual todas as solicitações de inferência são associadas a. Você pode criar mais projetos em sua conta usando a API de projetos.
## Quando usar projetos
Você deve usar a API de projetos quando precisar:
+ **Organize por estrutura de negócios**: gerencie o uso do Bedrock com base em sua taxonomia organizacional, como unidades de negócios, equipes, aplicativos ou centros de custo
+ **Isole dados confidenciais**: garanta que solicitações, respostas e dados de contexto de um aplicativo não estejam acessíveis a outros aplicativos
+ **Monitore os custos com precisão**: monitore e aloque os gastos com IA para equipes, projetos ou ambientes específicos
+ **Aplique políticas de acesso: aplique permissões granulares do IAM para controlar quem pode acessar cargas de trabalho** específicas de IA
+ **Dimensione as cargas de trabalho de produção**: execute vários aplicativos de produção com limites operacionais e monitoramento claros
## Projetos versus perfis de inferência
Tanto a API de projetos quanto os [perfis de inferência](inference-profiles-create.md) fornecem recursos de isolamento, marcação e controle de acesso no Amazon Bedrock, mas eles diferem com base na API que você usa. Se você estiver usando OpenAI compatível APIs com o endpoint [bedrock-mantle, que usa o mecanismo de inferência Mantle](endpoints.md), use a API de projetos. Se você estiver usando Invoke ou Converse APIs com o endpoint [bedrock-runtime](endpoints.md), use Perfis de inferência. Embora você possa usar a API Chat Completions com endpoints bedrock-mantle ou bedrock-runtime, recomendamos que você use o endpoint Mantle.
| Recurso | API de projetos | Perfis de inferência |
| --- | --- | --- |
| Suportado APIs | Compatível com OpenAI APIs (respostas, conclusão de bate-papo) | Native Bedrock APIs (Invoke, Converse), API compatível com OpenAI (conclusões de bate-papo) |
| Endpoint | bedrock-mantle.\$1region\$1.api.aws | bedrock-runtime.\$1region\$1.amazonaws.com |
| Caso de uso | Aplicativos usando endpoints compatíveis com OpenAI | Aplicativos usando o Bedrock nativo APIs |
| Controle de acesso | Projeto como recurso nas políticas do IAM | Políticas do IAM sobre o ARN do perfil de inferência |
| Controle de custos | Tags da AWS em projetos | Tags da AWS em perfis de inferência |
## Projetos versus contas da AWS
[As contas da](https://docs.aws.amazon.com/accounts/latest/reference/accounts-welcome.html) [AWS e as organizações da AWS](https://docs.aws.amazon.com/controltower/latest/userguide/organizations.html) representam os limites de faturamento e propriedade no nível da infraestrutura. Os projetos representam os limites da carga de trabalho e dos aplicativos em uma única conta.
O uso de projetos em vez de contas separadas da AWS fornece:
+ **Configuração mais rápida**: crie projetos em segundos por meio de chamadas de API
+ **Complexidade reduzida**: gerencie várias cargas de trabalho sem a expansão de contas
+ **Operações simplificadas**: gerenciamento centralizado em uma única conta
+ **Menor sobrecarga**: não há necessidade de funções do IAM entre contas ou compartilhamento de recursos
## Começando com projetos
Esta página explica como criar seu primeiro projeto, associá-lo a solicitações de inferência e gerenciar os recursos do projeto.
### Pré-requisitos
Antes de começar, verifique se você tem:
+ Uma conta da AWS com acesso ao Amazon Bedrock
+ Permissões do IAM para criar e gerenciar projetos Bedrock
+ Python 3.7 ou posterior instalado
+ O SDK do OpenAI Python instalado: `pip install openai boto3`
+ Uma [chave de API](api-keys.md) para autenticação do Amazon Bedrock
### Etapa 1: configurar seu ambiente
Configure suas variáveis de ambiente com suas credenciais do Amazon Bedrock:
```
export OPENAI_API_KEY=""
export OPENAI_BASE_URL="https://bedrock-mantle..api.aws/v1"
```
``Substitua pela sua região da AWS (por exemplo, us-east-1, us-west-2).
**nota**
O Amazon Bedrock oferece [dois tipos de chaves](https://docs.aws.amazon.com/bedrock/latest/userguide/api-keys-how.html): de curto e longo prazo. Embora você possa usar chaves de API de longo prazo para explorar o Amazon Bedrock, recomendamos chaves de curto prazo para aplicativos com maiores requisitos de segurança. Se você usa chaves de longo prazo com projetos, observe que a política padrão anexada às chaves de longo prazo só permite que você obtenha e liste projetos, mas não create/update/archive eles. Se você quiser que sua chave de longo prazo gerencie projetos, precisará atribuir políticas adicionais de IAM às suas chaves para permitir essas operações.
### Etapa 2: Descubra os modelos disponíveis
Use a `list()` API para recuperar uma lista de modelos compatíveis com a API de projetos:
```
curl -X GET $OPENAI_BASE_URL/models \
-H "Authorization: Bearer $OPENAI_API_KEY"
```
### Etapa 3: Crie seu primeiro projeto
Crie um projeto usando a API Create Project com tags para monitoramento de custos e observabilidade. Observe que, no momento, somente cURL é compatível com o 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
```
Resposta:
```
{
"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"
}
}
```
**Notas importantes:**
+ O parâmetro geográfico na especificação da API OpenAI é ignorado pelo Amazon Bedrock.
+ A região é determinada pela configuração do endpoint.
+ O campo arn é específico do Amazon Bedrock e fornece o ARN para o anexo da política do IAM.
+ As tags podem ser especificadas durante a criação do projeto e são retornadas em todas as respostas do projeto.
### Etapa 4: associar solicitações de inferência ao seu projeto
Para associar seu projeto às solicitações de inferência, forneça o ID do projeto ao criar o cliente:
------
#### [ 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")
```
------
Todas as solicitações de inferência feitas com esse cliente serão associadas ao projeto especificado, garantindo isolamento adequado, controle de custos e controle de acesso.
### Etapa 5: verifique a configuração do seu projeto
Liste todos os projetos para verificar se seu projeto foi criado com sucesso:
```
curl -X GET $OPENAI_BASE_URL/organization/projects \
-H "Authorization: Bearer $OPENAI_API_KEY"
```
Resposta:
```
{
"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"
}
```
### Próximas etapas
Agora que você criou seu primeiro projeto, você pode:
+ **Configure o controle de acesso**: anexe políticas do IAM para restringir o acesso ao projeto
+ **Configure o controle de custos**: adicione tags da AWS para alocação de custos
+ **Habilite o monitoramento**: configure CloudWatch métricas e alarmes
+ **Crie projetos adicionais**: organize cargas de trabalho por equipe, ambiente ou aplicativo
## Como trabalhar com projetos do
Esta página fornece informações detalhadas sobre o gerenciamento de projetos em todo o ciclo de vida.
### Criação de projetos
#### Criação básica de projetos
Crie um projeto com nome, descrição e tags:
```
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"
}
}'
```
Você pode ter até 1000 projetos por conta.
#### Convenções de nomenclatura recomendadas
Use nomes claros e descritivos que reflitam sua estrutura organizacional:
+ **Por aplicativo**: CustomerChatbot -Prod, -Dev InternalSearch
+ **Por equipe**: TeamAlpha -Produção, -Experimentos DataScience
+ **Por ambiente**: Produção-WebApp, Estadiamento- MobileApp
+ **Por centro de custo**: CostCenter -2152-Produção
### Listando projetos
#### Listar todos os projetos
Recupere todos os projetos em sua conta:
```
curl -X GET $OPENAI_BASE_URL/organization/projects \
-H "Authorization: Bearer $OPENAI_API_KEY"
```
### Recuperando detalhes do projeto
Obtenha informações detalhadas sobre um projeto específico:
```
curl -X GET $OPENAI_BASE_URL/organization/projects/proj_5d5ykleja6cwpirysbb7 \
-H "Authorization: Bearer $OPENAI_API_KEY"
```
### Atualizando projetos
Modifique as propriedades do projeto, como o 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"
}'
```
### Gerenciando tags de projeto
Adicione novas tags ou atualize os valores existentes:
```
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"
}
}'
```
Remova tags específicas usando suas chaves:
```
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"]
}'
```
**Observações importantes**
**Sem substituição completa**: não há nenhuma operação para substituir todo o conjunto de etiquetas de uma só vez. Você deve especificar explicitamente quais tags adicionar e quais remover.
**Tratamento de erros**: implemente o tratamento e a verificação adequados de erros
### Projetos de arquivamento
Arquive projetos que não estão mais em uso:
```
curl -X POST $OPENAI_BASE_URL/organization/projects/proj_abc123/archive \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json"
```
**Importante**
Os projetos arquivados não podem ser usados para novas solicitações de inferência, mas os dados e métricas históricos permanecem acessíveis por até 30 dias.
### Usando projetos com diferentes 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)
```
------
### Práticas recomendadas
#### Estrutura de projeto recomendada
**Um projeto por aplicativo**: crie projetos separados para cada aplicativo ou serviço distinto.
```
├── CustomerChatbot-Production
├── CustomerChatbot-Staging
├── CustomerChatbot-Development
├── InternalSearch-Production
└── InternalSearch-Development
```
+ **Ambientes separados**: use projetos diferentes para ambientes de desenvolvimento, preparação e produção.
+ **Isolamento de experimentos**: crie projetos dedicados para experimentos proof-of-concepts e.
#### Gerenciamento do ciclo de vida do projeto
+ **Crie projetos com antecedência**: configure projetos antes de implantar aplicativos
+ **Use nomenclatura consistente: siga as convenções** de nomenclatura organizacional
+ **Objetivo do projeto do documento**: incluir descrições claras
+ **Auditorias regulares**: revise e arquive periodicamente projetos não utilizados
+ **Monitore o uso**: acompanhe as métricas do projeto para identificar oportunidades de otimização