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á.
# Projetos (OpenAI-compatible)
A API Amazon Bedrock Projects fornece isolamento em nível de aplicativo para suas cargas de trabalho generativas de IA usando APIs. [ OpenAI-compatible ](bedrock-mantle.md) Os projetos permitem que você organize e gerencie seus aplicativos de IA com melhor controle de acesso, controle de custos e observabilidade em toda a organização.
**dica**
Para novos aplicativos, recomendamos o `bedrock-runtime` endpoint. Se você não precisa da API Projects, use Perfis de [ inferência ](inference-profiles-create.md) para isolamento, marcação e controle de custos. `bedrock-runtime`
**nota**
Os projetos só podem ser usados com modelos que usam as OpenAI-compatible APIs no endpoint [ básico. ](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 políticas [ do IAM para projetos Amazon Bedrock ](security-iam-projects.md)
+ **Monitoramento de custos**: acompanhe os gastos no nível do projeto usando tags [ da AWS ](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 em produção sem criar AWS contas ou organizações separadas, reduzindo a complexidade operacional e mantendo a segurança e a governança.
Cada AWS conta tem um projeto padrão ao qual todas as solicitações de inferência estão associadas. Você pode criar mais projetos em sua conta usando a API Projects.
**nota**
O suporte para projetos difere de acordo com o endpoint. No `bedrock-mantle` endpoint, você pode criar e gerenciar seus próprios projetos com a API Projects. No `bedrock-runtime` endpoint, somente o projeto padrão está disponível — você ainda não pode criar projetos lá. Solicitações para `bedrock-runtime` resolver o projeto padrão da sua conta, cujo ARN é`arn:aws:bedrock:{{region}}:{{account-id}}:project/default`. O projeto padrão não pode ser marcado nem excluído, sua configuração de retenção de dados sempre é herdada da conta e nunca é a âncora de cobrança: o uso em `bedrock-runtime` é atribuído à meta de inferência, exatamente como é hoje. Para obter as permissões que fazem referência ao projeto padrão, consulte[Pré-requisitos para executar a inferência do modelo](inference-prereq.md).
## Quando usar projetos
Você deve usar a API Projects 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
+ **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 no endpoint que você usa. Se você estiver usando OpenAI-compatible APIs com o [ endpoint ](endpoints.md) bedrock-mantle, use a API Projects. Se você estiver usando o [ endpoint ](endpoints.md) bedrock-runtime (recomendado para novos aplicativos), use Perfis de inferência. A API Chat Complements está disponível em ambos os endpoints; a API Projects está disponível somente em. `bedrock-mantle`
| Recurso | API de projetos | Perfis de inferência |
| --- | --- | --- |
| APIs aceitas do : | OpenAI-compatible APIs (respostas, conclusão de bate-papos) | APIs Native Bedrock (Invoke, Converse), OpenAI-compatible API (conclusões de bate-papo) |
| Endpoint | bedrock-mantle.{region}.api.aws | bedrock-runtime.{region}.amazonaws.com |
| Caso de uso | Aplicativos usando OpenAI-compatible endpoints | Aplicativos usando APIs nativas do Bedrock |
| Controle de acesso | Projeto como recurso nas políticas do IAM | Políticas do IAM no perfil de inferência ARN |
| Acompanhamento de custos | AWS tags em projetos | AWS tags em perfis de inferência |
## Projetos vs. AWS contas
[As contas ](https://docs.aws.amazon.com/accounts/latest/reference/accounts-welcome.html) e [AWS organizações da AWS ](https://docs.aws.amazon.com/controltower/latest/userguide/organizations.html) representam 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 AWS contas separadas 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 de IAM entre contas ou compartilhamento de recursos
## Começando com Projetos
Esta página explica como criar seu primeiro projeto, associá-lo às solicitações de inferência e gerenciar os recursos do projeto.
### Pré-requisitos
Antes de começar, você deve ter o seguinte:
+ Uma AWS conta com acesso ao Amazon Bedrock
+ Permissões do IAM para criar e gerenciar projetos Bedrock
+ Python 3.7 ou posterior instalado
+ O SDK 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 AWS região (por exemplo, us-east-1, us-west-2).
**nota**
O Amazon Bedrock oferece [ dois tipos de chaves](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ê usar chaves de longo prazo com Projetos, observe que a política padrão anexada às chaves de longo prazo só permite obter e listar projetos, mas não create/update /arquivá-los. Se você quiser que sua chave de longo prazo gerencie projetos, você precisará atribuir políticas de IAM adicionais às suas chaves para habilitar 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 Projects:
```
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 e observabilidade de custos. Observe que, no momento, somente o cURL é suportado no 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 seu endpoint.
+ O campo arn é específico do Amazon Bedrock e fornece o ARN para o anexo de políticas 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: Verificar 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:
+ **Configurar o controle de acesso**: anexe políticas do IAM para restringir o acesso ao projeto
+ **Configurar o controle de custos**: adicione AWS tags 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/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, InternalSearch-Dev
+ **Por equipe**: TeamAlpha-Production, DataScience-Experiments
+ **Por ambiente**: Production-WebApp, Staging-MobileApp
+ **Por centro de custo**: CostCenter-2152-Production
### 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 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 das tags 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 por meio de 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á operação para substituir todo o conjunto de tags 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**
Projetos arquivados não podem ser usados para novas solicitações de inferência, mas dados históricos e métricas 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 e provas de conceitos.
#### 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