本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 项目 API
<a name="projects"></a>

[Amazon Bedrock Projects API 使用兼容 OpenAI 的方式，为您的生成人工智能工作负载提供应用程序级隔离。 APIs](bedrock-mantle.md)项目使您能够通过改进整个组织的访问控制、成本跟踪和可观察性来组织和管理 AI 应用程序。

**注意**  
项目只能与使用兼容 OpenAI APIs 的模型与[基岩](bedrock-mantle.md)地幔端点搭配使用。如果您使用的是 bedrock-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 标签和 AWS](https://docs.aws.amazon.com/whitepapers/latest/tagging-best-practices/what-are-tags.html) 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 的使用情况
+ **隔离敏感数据**：确保其他应用程序无法访问来自一个应用程序的提示、响应和上下文数据
+ **准确跟踪成本**：监控人工智能支出并将其分配给特定团队、项目或环境
+ **强制执行访问策略**：应用精细的 IAM 权限来控制谁可以访问特定 AI 工作负载
+ **扩展生产工作负载**：在明确的运营界限和监控的情况下运行多个生产应用程序

## 项目与推理配置文件
<a name="projects-vs-inference-profiles"></a>

Projects API 和[推理配置文件](inference-profiles-create.md)都在 Amazon Bedrock 中提供隔离、标记和访问控制功能，但它们因您使用的 API 而异。如果你使用与 OpenAI 兼容的 b [edrock- APIs mantle](endpoints.md) 端点（使用 Mantle 推理引擎），请使用 Projects API。如果您将 Invo [ke 或 Converse APIs 与基底运行时端点一起使用，请使用推](endpoints.md)理配置文件。虽然你可以将 Chat Completions API 与 bedrock-mantle 或基岩运行时端点一起使用，但我们建议你使用 Mantle 端点。


| 功能 | 项目 API | 推理配置文件 | 
| --- | --- | --- | 
| 支持的 APIs | 兼容 OpenAI APIs （回复、聊天完成） | Native Bedrock APIs （调用、Converse）、兼容 OpenAI 的 API（聊天完成） | 
| 端点 | bedrock-mantle.\$1region\$1.api.aws | bedrock-runtime.\$1region\$1.amazonaws.com | 
| 使用场景 | 使用兼容 OpenAI 的端点的应用程序 | 使用原生 Bedrock 的应用程序 APIs | 
| 访问控制 | 在 IAM 策略中将项目作为资源 | 推理配置文件上的 IAM 策略 ARN | 
| 成本跟踪 | 项目上的 AWS 标签 | 推理配置文件上的 AWS 标签 | 

## 项目与 AWS 账户
<a name="projects-vs-aws-accounts"></a>

[AWS 账户](https://docs.aws.amazon.com/accounts/latest/reference/accounts-welcome.html)和 [AWS Org](https://docs.aws.amazon.com/controltower/latest/userguide/organizations.html) anizations 代表基础设施级别的账单和所有权界限。项目代表单个账户内的工作负载和应用程序边界。

使用项目代替单独的 AWS 账户可提供：
+ **更快的设置**：通过 API 调用在几秒钟内创建项目
+ **降低复杂性**：管理多个工作负载，避免账户扩张
+ **简化操作**：在一个账户内进行集中管理
+ **降低开销**：无需跨账户 IAM 角色或资源共享

## 项目入门
<a name="projects-getting-started"></a>

本页将引导您创建第一个项目、将其与推理请求关联以及管理项目资源。

### 先决条件
<a name="projects-prerequisites"></a>

在开始之前，请确保您满足以下条件：
+ 具有亚马逊 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，但对于安全要求更高的应用程序，我们建议使用短期密钥。如果您在 Projects 中使用长期密钥，请注意，附加到长期密钥的默认策略仅允许您获取和列出项目，但不允许获取和列create/update/archive出项目。如果您希望使用长期密钥来管理项目，则必须为密钥分配其他 IAM 策略才能启用这些操作。

### 第 2 步：发现可用型号
<a name="projects-discover-models"></a>

使用 `list()` API 检索与 Projects API 兼容的模型列表：

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

### 第 3 步：创建您的第一个项目
<a name="projects-create-first"></a>

使用带有成本监控和可观察性标签的 Create Project API 创建项目。请注意，目前软件开发工具包中仅支持 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、-Dev InternalSearch
+ **按团队划分**： TeamAlpha-制作， DataScience-实验
+ **按环境划**分：生产-WebApp、暂存-MobileApp
+ **按成本中心**划分： CostCenter-2152-产量

### 列出项目
<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>
+ **尽早创建项目**：在部署应用程序之前设置项目
+ **使用一致的命名**：遵循组织命名惯例
+ **记录项目目的**：包括清晰的描述
+ **定期审计**：定期审查和存档未使用的项目
+ **监控使用情况**：跟踪项目指标以确定优化机会