기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
# 프로젝트 API
Amazon Bedrock Projects API는 [OpenAI 호환 APIs](bedrock-mantle.md). 프로젝트를 사용하면 조직 전체에서 향상된 액세스 제어, 비용 추적 및 관찰성을 통해 AI 애플리케이션을 구성하고 관리할 수 있습니다.
**참고**
프로젝트는 [bedrock-mantle 엔드포인트](bedrock-mantle.md)에 대해 OpenAI 호환 APIs를 사용하는 모델에서만 사용할 수 있습니다. bedrock-runtime 엔드포인트를 사용하는 경우 태그 지정 및 관찰성 대신 추론 프로파일을 사용하세요.
## 프로젝트란 무엇입니까?
프로젝트는 Amazon Bedrock 내에서 애플리케이션, 환경 또는 실험과 같은 워크로드를 격리하는 데 사용되는 논리적 경계입니다. 프로젝트에서는 다음을 제공합니다.
+ **액세스 격리**: [AWS Identity and Access Management(IAM) 정책을](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html) 사용하여 특정 프로젝트 리소스에 액세스할 수 있는 사용자 제어
+ **비용 모니터링**: [AWS 태그](https://docs.aws.amazon.com/whitepapers/latest/tagging-best-practices/what-are-tags.html) 및 [AWS Cost Explorer](https://docs.aws.amazon.com/cost-management/latest/userguide/ce-what-is.html)를 사용하여 프로젝트 수준에서 지출 추적
프로젝트를 사용하면 별도의 AWS 계정 또는 조직을 생성하지 않고도 프로덕션 환경에서 여러 생성형 AI 워크로드를 관리할 수 있으므로 보안 및 거버넌스를 유지하면서 운영 복잡성을 줄일 수 있습니다.
각 AWS 계정에는 모든 추론 요청이 연결된 기본 프로젝트가 있습니다. 프로젝트 API를 사용하여 계정에 더 많은 프로젝트를 생성할 수 있습니다.
## 프로젝트를 사용해야 하는 경우
다음과 같은 경우 프로젝트 API를 사용해야 합니다.
+ **비즈니스 구조별 구성**: 사업부, 팀, 애플리케이션 또는 비용 센터와 같은 조직 분류를 기반으로 Bedrock 사용량 관리
+ **민감한 데이터 격리**: 한 애플리케이션의 프롬프트, 응답 및 컨텍스트 데이터에 다른 애플리케이션이 액세스할 수 없도록 합니다.
+ **비용을 정확하게 추적**: AI 지출을 모니터링하고 특정 팀, 프로젝트 또는 환경에 할당
+ **액세스 정책 적용**: 세분화된 IAM 권한을 적용하여 특정 AI 워크로드에 액세스할 수 있는 사용자를 제어합니다.
+ **프로덕션 워크로드 규모 조정**: 명확한 운영 경계 및 모니터링으로 여러 프로덕션 애플리케이션 실행
## 프로젝트와 추론 프로파일 비교
프로젝트 API와 [추론 프로파일](inference-profiles-create.md) 모두 Amazon Bedrock에서 격리, 태그 지정 및 액세스 제어 기능을 제공하지만 사용하는 API에 따라 다릅니다. Mantle 추론 엔진을 사용하는 [bedrock-mantle](endpoints.md) 엔드포인트와 함께 OpenAI 호환 APIs를 사용하는 경우 프로젝트 API를 사용합니다. [bedrock-runtime](endpoints.md) 엔드포인트와 함께 Invoke 또는 Converse APIs를 사용하는 경우 추론 프로파일을 사용합니다. 채팅 완료 API를 bedrock-mantle 또는 bedrock-runtime 엔드포인트와 함께 사용할 수 있지만 Mantle 엔드포인트를 사용하는 것이 좋습니다.
| 기능 | 프로젝트 API | 추론 프로파일 |
| --- | --- | --- |
| 지원되는 API | OpenAI 호환 APIs(응답, 채팅 완료) | 네이티브 Bedrock APIs(Invoke, Converse), OpenAI 호환 API(챗 완료) |
| 엔드포인트 | bedrock-mantle.\$1region\$1.api.aws | bedrock-runtime.\$1region\$1.amazonaws.com |
| 사용 사례 | OpenAI 호환 엔드포인트를 사용하는 애플리케이션 | 네이티브 Bedrock APIs 사용하는 애플리케이션 |
| 액세스 통제 | IAM 정책의 리소스로 프로젝트 | 추론 프로필 ARN에 대한 IAM 정책 |
| 비용 추적 | 프로젝트의 AWS 태그 | 추론 프로필의 AWS 태그 |
## 프로젝트와 AWS 계정 비교
[AWS 계정](https://docs.aws.amazon.com/accounts/latest/reference/accounts-welcome.html) 및 [AWS Organizations](https://docs.aws.amazon.com/controltower/latest/userguide/organizations.html) 인프라 수준에서 결제 및 소유권 경계를 나타냅니다. 프로젝트는 단일 계정 내의 워크로드 및 애플리케이션 경계를 나타냅니다.
별도의 AWS 계정 대신 프로젝트를 사용하면 다음과 같은 이점이 있습니다.
+ **더 빠른 설정**: API 직접 호출을 통해 몇 초 만에 프로젝트 생성
+ **복잡성 감소**: 계정 확장 없이 여러 워크로드 관리
+ **간소화된 작업**: 단일 계정 내의 중앙 집중식 관리
+ **오버헤드 감소**: 교차 계정 IAM 역할 또는 리소스 공유 필요 없음
## 프로젝트 시작하기
이 페이지에서는 첫 번째 프로젝트를 생성하고, 추론 요청과 연결하고, 프로젝트 리소스를 관리하는 방법을 안내합니다.
### 사전 조건
시작하기 전에 다음을 갖추었는지 확인하세요.
+ Amazon Bedrock 액세스 권한이 있는 AWS 계정
+ Bedrock 프로젝트를 생성하고 관리할 수 있는 IAM 권한
+ Python 3.7 이상 설치됨
+ OpenAI Python SDK가 설치되었습니다. `pip install openai boto3`
+ Amazon Bedrock 인증을 위한 [API 키](api-keys.md)
### 1단계: 환경 설정
Amazon Bedrock 자격 증명을 사용하여 환경 변수를 구성합니다.
```
export OPENAI_API_KEY=""
export OPENAI_BASE_URL="https://bedrock-mantle..api.aws/v1"
```
를 AWS 리전(예: us-east-1, us-west-2)``으로 바꿉니다.
**참고**
Amazon Bedrock은 단기 및 장기[라는 두 가지 유형의 키를](https://docs.aws.amazon.com/bedrock/latest/userguide/api-keys-how.html) 제공합니다. Amazon Bedrock 탐색에 장기 API 키를 사용할 수 있지만 보안 요구 사항이 더 높은 애플리케이션에는 단기 키를 사용하는 것이 좋습니다. 장기 키를 프로젝트와 함께 사용하는 경우 장기 키에 연결된 기본 정책은 프로젝트를 가져오고 나열할 뿐 create/update/archive할 수는 없다는 점에 유의하세요. 장기 키를 사용하여 프로젝트를 관리하려면 키에 추가 IAM 정책을 할당하여 이러한 작업을 활성화해야 합니다.
### 2단계: 사용 가능한 모델 검색
`list()` API를 사용하여 프로젝트 API와 호환되는 모델 목록을 검색합니다.
```
curl -X GET $OPENAI_BASE_URL/models \
-H "Authorization: Bearer $OPENAI_API_KEY"
```
### 3단계: 첫 번째 프로젝트 생성
비용 모니터링 및 관찰성을 위한 태그가 있는 프로젝트 생성 API를 사용하여 프로젝트를 생성합니다. 현재 SDK에서는 cURL만 지원됩니다.
```
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
```
응답:
```
{
"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"
}
}
```
**중요 참고 사항:**
+ OpenAI API 사양의 지리 파라미터는 Amazon Bedrock에서 무시됩니다.
+ 리전은 엔드포인트 구성에 따라 결정됩니다.
+ ARN 필드는 Amazon Bedrock에 고유하며 IAM 정책 연결을 위한 ARN을 제공합니다.
+ 태그는 프로젝트 생성 중에 지정할 수 있으며 모든 프로젝트 응답에 반환됩니다.
### 4단계: 추론 요청을 프로젝트와 연결
프로젝트를 추론 요청에 연결하려면 클라이언트를 생성할 때 프로젝트 ID를 제공합니다.
------
#### [ 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")
```
------
이 클라이언트로 이루어진 모든 추론 요청은 지정된 프로젝트와 연결되어 적절한 격리, 비용 추적 및 액세스 제어를 보장합니다.
### 5단계: 프로젝트 설정 확인
모든 프로젝트를 나열하여 프로젝트가 성공적으로 생성되었는지 확인합니다.
```
curl -X GET $OPENAI_BASE_URL/organization/projects \
-H "Authorization: Bearer $OPENAI_API_KEY"
```
응답:
```
{
"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"
}
```
### 다음 단계
이제 첫 번째 프로젝트를 생성했으므로 다음을 수행할 수 있습니다.
+ **액세스 제어 구성**: IAM 정책을 연결하여 프로젝트 액세스 제한
+ **비용 추적 설정**: 비용 할당을 위한 AWS 태그 추가
+ **모니터링 활성화**: CloudWatch 지표 및 경보 구성
+ **추가 프로젝트 생성**: 팀, 환경 또는 애플리케이션별로 워크로드 구성
## 프로젝트 작업
이 페이지에서는 수명 주기 동안 프로젝트 관리에 대한 자세한 정보를 제공합니다.
### 프로젝트 생성
#### 기본 프로젝트 생성
이름, 설명 및 태그를 사용하여 프로젝트를 생성합니다.
```
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"
}
}'
```
계정당 최대 1,000개의 프로젝트를 보유할 수 있습니다.
#### 권장 이름 지정 규칙
조직 구조를 반영하는 명확하고 설명적인 이름을 사용합니다.
+ **애플리케이션별**: CustomerChatbot-Prod, InternalSearch-Dev
+ **팀별**: TeamAlpha-Production, DataScience-Experiments
+ **환경별**: Production-WebApp, Staging-MobileApp
+ **비용 센터별**: CostCenter-2152-Production
### 프로젝트 나열
#### 모든 프로젝트 나열
계정의 모든 프로젝트를 검색합니다.
```
curl -X GET $OPENAI_BASE_URL/organization/projects \
-H "Authorization: Bearer $OPENAI_API_KEY"
```
### 프로젝트 세부 정보 검색
특정 프로젝트에 대한 자세한 정보를 가져옵니다.
```
curl -X GET $OPENAI_BASE_URL/organization/projects/proj_5d5ykleja6cwpirysbb7 \
-H "Authorization: Bearer $OPENAI_API_KEY"
```
### 프로젝트 업데이트
다음과 같은 프로젝트 속성을 수정합니다.
```
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"
}'
```
### 프로젝트 태그 관리
새 태그를 추가하거나 기존 태그 값을 업데이트합니다.
```
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"
}
}'
```
키로 특정 태그를 제거합니다.
```
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"]
}'
```
**중요 정보**
**전체 교체 없음**: 전체 태그 세트를 한 번에 교체하는 작업이 없습니다. 추가할 태그와 제거할 태그를 명시적으로 지정해야 합니다.
**오류 처리**: 적절한 오류 처리 및 확인 구현
### 프로젝트 아카이빙
더 이상 사용되지 않는 프로젝트를 아카이브합니다.
```
curl -X POST $OPENAI_BASE_URL/organization/projects/proj_abc123/archive \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json"
```
**중요**
보관된 프로젝트는 새 추론 요청에 사용할 수 없지만 기록 데이터 및 지표는 최대 30일 동안 액세스할 수 있습니다.
### 다른 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)
```
------
### 모범 사례
#### 권장 프로젝트 구조
**애플리케이션당 프로젝트 1**개: 각 개별 애플리케이션 또는 서비스에 대해 별도의 프로젝트를 생성합니다.
```
├── CustomerChatbot-Production
├── CustomerChatbot-Staging
├── CustomerChatbot-Development
├── InternalSearch-Production
└── InternalSearch-Development
```
+ **별도의 환경**: 개발, 스테이징 및 프로덕션 환경에 다른 프로젝트를 사용합니다.
+ **실험 격리**: 실험 및 proof-of-concepts 위한 전용 프로젝트를 생성합니다.
#### 프로젝트 수명 주기 관리
+ **프로젝트 조기 생성**: 애플리케이션을 배포하기 전에 프로젝트 설정
+ **일관된 이름 지정 사용**: 조직 이름 지정 규칙 준수
+ **문서 프로젝트 목적**: 명확한 설명 포함
+ **정기 감사**: 사용하지 않는 프로젝트를 정기적으로 검토 및 보관
+ **사용량 모니터링**: 프로젝트 지표를 추적하여 최적화 기회 식별