本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 專案 API
<a name="projects"></a>

Amazon Bedrock Projects API 使用 [OpenAI 相容 APIs](bedrock-mantle.md) 為您的生成式 AI 工作負載提供應用程式層級隔離。專案可讓您透過改善的存取控制、成本追蹤和整個組織的可觀測性來組織和管理 AI 應用程式。

**注意**  
專案只能與針對 [bedrock-mantle 端點](bedrock-mantle.md)使用 OpenAI 相容 APIs的模型搭配使用。如果您使用的是底ock-runtime 端點，請使用推論設定檔，而不是標記和可觀測性。

## 什麼是專案？
<a name="projects-what-is"></a>

專案是一種邏輯界限，用於隔離 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) 追蹤專案層級的支出

專案可讓您在生產環境中管理多個生成式 AI 工作負載，而無需建立單獨的 AWS 帳戶或組織，從而降低操作複雜性，同時維護安全性和管理。

每個 AWS 帳戶都有一個預設專案，其中會與所有推論請求建立關聯。您可以使用專案 API 在帳戶中建立更多專案。

## 何時使用專案
<a name="projects-when-to-use"></a>

當您需要以下項目時，應該使用專案 API：
+ **依業務結構組織**：根據您的組織分類管理 Bedrock 用量，例如業務單位、團隊、應用程式或成本中心
+ **隔離敏感資料**：確保其他應用程式無法存取來自某個應用程式的提示、回應和內容資料
+ **準確追蹤成本**：監控並配置 AI 支出給特定團隊、專案或環境
+ **強制執行存取政策**：套用精細的 IAM 許可，以控制誰可以存取特定 AI 工作負載
+ **擴展生產工作負載**：執行多個具有明確操作界限和監控的生產應用程式

## 專案與推論設定檔
<a name="projects-vs-inference-profiles"></a>

專案 API [和推論設定檔](inference-profiles-create.md)在 Amazon Bedrock 中提供隔離、標記和存取控制功能，但它們會根據您使用的 API 而有所不同。如果您將 OpenAI 相容 APIs與使用 Mantle 推論引擎的 [bedrock-mantle](endpoints.md) 端點搭配使用，請使用 Projects API。如果您使用 Invoke 或 Converse APIs搭配 [bedrock-runtime](endpoints.md) 端點，請使用推論設定檔。雖然您可以將聊天完成 API 與 bedrock-mantle 或 bedrock-runtime 端點搭配使用，但我們建議您使用 Mantle 端點。


| 功能 | 專案 API | 推論設定檔 | 
| --- | --- | --- | 
| 支援的 API | OpenAI 相容 APIs （回應、聊天完成） | 原生 Bedrock APIs（調用、Converse)、OpenAI 相容 API （聊天完成） | 
| Endpoint | bedrock-mantle.\$1region\$1.api.aws | bedrock-runtime.\$1region\$1.amazonaws.com | 
| 使用案例 | 使用 OpenAI 相容端點的應用程式 | 使用原生 Bedrock APIs的應用程式 | 
| 存取控制 | 在 IAM 政策中將 投影為資源 | 推論設定檔 ARN 的 IAM 政策 | 
| 成本追蹤 | 專案上的 AWS 標籤 | 推論設定檔上的 AWS 標籤 | 

## 專案與 AWS 帳戶
<a name="projects-vs-aws-accounts"></a>

[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 角色或資源共用

## 專案入門
<a name="projects-getting-started"></a>

此頁面會逐步引導您建立第一個專案、將其與推論請求建立關聯，以及管理專案資源。

### 先決條件
<a name="projects-prerequisites"></a>

開始前，請確保您具備以下條件：
+ 具有 Amazon Bedrock 存取權的 AWS 帳戶
+ 建立和管理 Bedrock 專案的 IAM 許可
+ 已安裝 Python 3.7 或更新版本
+ 已安裝 OpenAI Python SDK： `pip install openai boto3`
+ Amazon Bedrock 身分驗證的 [API 金鑰](api-keys.md) 

### 步驟 1：設定您的環境
<a name="projects-setup-environment"></a>

使用 Amazon Bedrock 登入資料設定您的環境變數：

```
export OPENAI_API_KEY="<your-bedrock-key>"
export OPENAI_BASE_URL="https://bedrock-mantle.<your-region>.api.aws/v1"
```

將 取代`<your-region>`為您的 AWS 區域 （例如 us-east-1、us-west-2)。

**注意**  
Amazon Bedrock 提供[兩種類型的金鑰](https://docs.aws.amazon.com/bedrock/latest/userguide/api-keys-how.html)：短期和長期。雖然您可以使用長期 API 金鑰來探索 Amazon Bedrock，但我們建議具有較高安全需求的應用程式使用短期金鑰。如果您將長期金鑰與專案搭配使用，請注意，連接至長期金鑰的預設政策僅允許您取得和列出專案，但無法create/update/archive專案。如果您想要長期金鑰來管理專案，則必須將其他 IAM 政策指派給金鑰，才能啟用這些操作。

### 步驟 2：探索可用的模型
<a name="projects-discover-models"></a>

使用 `list()` API 擷取與專案 API 相容的模型清單：

```
curl -X GET $OPENAI_BASE_URL/models \
  -H "Authorization: Bearer $OPENAI_API_KEY"
```

### 步驟 3：建立您的第一個專案
<a name="projects-create-first"></a>

使用具有成本監控和可觀測性標籤的建立專案 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"
  }
}
```

**重要備註：**
+ Amazon Bedrock 會忽略 OpenAI API 規格中的地理參數。
+ 區域取決於您的端點組態。
+ arn 欄位專屬於 Amazon Bedrock，並提供 IAM 政策連接的 ARN。
+ 您可以在專案建立期間指定標籤，並在所有專案回應中傳回。

### 步驟 4：將推論請求與您的專案建立關聯
<a name="projects-associate-inference"></a>

若要將專案與推論請求建立關聯，請在建立用戶端時提供專案 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：驗證您的專案設定
<a name="projects-verify-setup"></a>

列出所有專案，以確認您的專案已成功建立：

```
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"
}
```

### 後續步驟
<a name="projects-next-steps"></a>

現在您已建立第一個專案，您可以：
+ **設定存取控制**：連接 IAM 政策以限制專案存取
+ **設定成本追蹤**：為成本分配新增 AWS 標籤
+ **啟用監控**：設定 CloudWatch 指標和警示
+ **建立其他專案**：依團隊、環境或應用程式組織工作負載

## 使用 專案
<a name="projects-working-with"></a>

此頁面提供有關在整個生命週期中管理專案的詳細資訊。

### 建立專案
<a name="projects-creating"></a>

#### 基本專案建立
<a name="projects-basic-creation"></a>

建立具有名稱、描述和標籤的專案：

```
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"
    }
  }'
```

每個帳戶最多可有 1000 個專案。

#### 建議的命名慣例
<a name="projects-naming-conventions"></a>

使用清楚的描述性名稱來反映您的組織結構：
+ **依應用程式**：CustomerChatbot-Prod、InternalSearch-Dev
+ **依團隊**：TeamAlpha-Production、DataScience-Experiments
+ **依環境**：Production-WebApp、Staging-MobileApp
+ **依成本中心**：CostCenter-2152-Production

### 列出專案
<a name="projects-listing"></a>

#### 列出所有專案
<a name="projects-list-all"></a>

擷取您帳戶中的所有專案：

```
curl -X GET $OPENAI_BASE_URL/organization/projects \
  -H "Authorization: Bearer $OPENAI_API_KEY"
```

### 擷取專案詳細資訊
<a name="projects-retrieving-details"></a>

取得特定專案的詳細資訊：

```
curl -X GET $OPENAI_BASE_URL/organization/projects/proj_5d5ykleja6cwpirysbb7 \
  -H "Authorization: Bearer $OPENAI_API_KEY"
```

### 更新專案
<a name="projects-updating"></a>

修改專案屬性，例如名稱：

```
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"
  }'
```

### 管理專案標籤
<a name="projects-managing-tags"></a>

新增標籤或更新現有的標籤值：

```
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"]
  }'
```

**重要說明**  
**不完全取代**：沒有可一次取代整個標籤集的操作。您必須明確指定要新增的標籤和要移除的標籤。
**錯誤處理**：實作適當的錯誤處理和驗證

### 封存專案
<a name="projects-archiving"></a>

封存不再使用的專案：

```
curl -X POST $OPENAI_BASE_URL/organization/projects/proj_abc123/archive \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json"
```

**重要**  
封存的專案無法用於新的推論請求，但歷史資料和指標仍可存取長達 30 天。

### 使用具有不同 APIs專案
<a name="projects-using-apis"></a>

------
#### [ 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)
```

------

### 最佳實務
<a name="projects-best-practices"></a>

#### 建議的專案結構
<a name="projects-recommended-structure"></a>

**每個應用程式一個專案**：為每個不同的應用程式或服務建立個別專案。

```
├── CustomerChatbot-Production
├── CustomerChatbot-Staging
├── CustomerChatbot-Development
├── InternalSearch-Production
└── InternalSearch-Development
```
+ **個別環境**：針對開發、預備和生產環境使用不同的專案。
+ **實驗隔離**：為實驗和proof-of-concepts建立專用專案。

#### 專案生命週期管理
<a name="projects-lifecycle-management"></a>
+ **提早建立專案**：在部署應用程式之前設定專案
+ **使用一致的命名**：遵循組織命名慣例
+ **文件專案目的**：包含明確描述
+ **定期稽核**：定期檢閱和封存未使用的專案
+ **監控用量**：追蹤專案指標以識別最佳化機會