如需查看完整的文档索引,请参阅 llms.txt。在文档页面的 URL 末尾加上 .md 即可查看该页面的 Markdown 版本。
主导航
主题

设置非对称密钥

注册由云服务商管理的公钥,供 OpenAI 使用

将云服务商提供的 RSA-3072 非对称密钥对注册到 OpenAI。

您的私钥始终保存在 AWS KMS、Azure Key Vault、Google Cloud KMS 或 Oracle Cloud Infrastructure (OCI) Vault 中。注册时,OpenAI 会保存对应公钥的副本。

注册密钥不会自动配置产品功能或存储。本指南介绍如何设置用于 PSP 解密的密钥。

开始前的准备

  • 准备好您的组织 ID。配置云端信任关系、注册密钥和访问 API 时,请使用同一组织。
  • 创建一个具有外部密钥读写权限的组织管理 API 密钥,并以安全方式将其加载到 OPENAI_ADMIN_KEY 环境变量中。项目推理密钥无法用于此操作。
  • 确认您有权创建并启用 RSA-3072 密钥,并能按照本指南限定的范围向 OpenAI 授予公钥读取权限。
  • 仅允许获授权的用户使用私钥。只要还有记录依赖旧版本的密钥,就要保留该版本。

设置云端密钥

注册密钥前,请按您的云服务商对应的步骤操作。以下配置均使用 RSA-3072,并且仅允许 OpenAI 读取公钥和密钥元数据。

注册密钥

以下示例使用 curl 和兼容 Bash 的 shell。以安全方式加载 OPENAI_ADMIN_KEY,然后设置您的组织 ID:

API_BASE="https://api.openai.com/v1"
ORG_ID="<OPENAI_ORG_ID>"

: "${OPENAI_ADMIN_KEY:?Load your organization admin key securely}"

KEYS_URL="$API_BASE/organization/external_keys"

准备注册请求

purpose 枚举接受 ekm(默认值)或 psp_decryption。对于本指南中的非对称密钥,请使用 psp_decryption。ekm 用于企业密钥管理(EKM)。

将您的云服务商对应的请求保存为 registration.json。请将示例值替换为实际值,JSON 不会展开 shell 变量。

AWS KMS 请求

{
  "type": "aws",
  "purpose": "psp_decryption",
  "name": "asymmetric-key-aws",
  "role_arn": "<CUSTOMER_ROLE_ARN>",
  "external_id": "<OPENAI_ORG_ID>",
  "kms_arn": "<CUSTOMER_KMS_KEY_ARN>"
}

Azure Key Vault 请求

{
  "type": "azure",
  "purpose": "psp_decryption",
  "name": "asymmetric-key-azure",
  "tenant_id": "<CUSTOMER_TENANT_ID>",
  "vault_uri": "https://<CUSTOMER_VAULT_NAME>.vault.azure.net",
  "key_name": "<OPENAI_ORG_ID>--asymmetric-key",
  "key_version": "<CUSTOMER_KEY_VERSION>"
}

Google Cloud KMS 请求

{
  "type": "gcp",
  "purpose": "psp_decryption",
  "name": "asymmetric-key-gcp",
  "workload_identity_project_number": "<CUSTOMER_GCP_PROJECT_NUMBER>",
  "workload_identity_pool_id": "openai-keys",
  "workload_identity_provider_id": "openai-google",
  "audience": "<OPENAI_ORG_ID>",
  "kms_project_id": "<CUSTOMER_KMS_PROJECT_ID>",
  "kms_key_ring_name": "asymmetric-keys",
  "kms_key_name": "asymmetric-key",
  "kms_key_location": "us-central1",
  "kms_key_version": "1"
}

OCI Vault 请求

{
  "type": "oci",
  "purpose": "psp_decryption",
  "name": "asymmetric-key-oci",
  "region": "us-ashburn-1",
  "vault_ocid": "<CUSTOMER_VAULT_OCID>",
  "key_ocid": "<CUSTOMER_KEY_OCID>",
  "key_version_ocid": "<CUSTOMER_KEY_VERSION_OCID>"
}

1. 注册并验证密钥

curl --fail-with-body -sS "$KEYS_URL" \
  -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \
  -H "OpenAI-Organization: $ORG_ID" \
  -H "Content-Type: application/json" \
  --data @registration.json

注册时,系统会先验证密钥,再保存注册信息。注册成功后,API 会返回 HTTP 200,响应中包含 extkey ID 和您的云服务商配置。以下是部分响应字段的示例:

{
  "id": "extkey_11111111111111111111111111111111",
  "object": "organization.external_key",
  "name": "asymmetric-key-gcp",
  "type": "gcp",
  "purpose": "psp_decryption",
  "api_project_ids": []
}

保存返回的注册 ID:

KEY_ID="<EXTERNAL_KEY_ID>"

2. 重新验证密钥(可选)

GET 返回已保存的详细信息。POST /validate 会重新检查当前访问权限,并对照已保存的公钥检查密钥是否仍然有效。此操作不会解密记录或刷新快照。

curl --fail-with-body -sS "$KEYS_URL/$KEY_ID" \
  -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \
  -H "OpenAI-Organization: $ORG_ID"
curl --fail-with-body -sS -X POST "$KEYS_URL/$KEY_ID/validate" \
  -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \
  -H "OpenAI-Organization: $ORG_ID"

预期响应(HTTP 200):

{ "status": "success" }

更改密钥、权限或网络配置后,请重新验证。如果更改了 IAM 配置,请等待更改生效后再重试。

要使用已注册的密钥进行 PSP 解密,请为项目选择该密钥。

列出密钥

使用 purpose=psp_decryption 列出用于 PSP 解密的非对称密钥注册记录。省略此筛选条件会返回所有用途的注册记录。使用 purpose=ekm 则仅返回用于 EKM 的注册记录。

curl --fail-with-body -sS --get "$KEYS_URL" \
  -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \
  -H "OpenAI-Organization: $ORG_ID" \
  --data-urlencode "purpose=psp_decryption" \
  --data-urlencode "order=asc" \
  --data-urlencode "limit=20"

只要 has_more 为 true,就将 after 设置为 last_id 的值并请求下一页。保持 purpose、order 和 limit 的值不变。

更换密钥

  1. 在 AWS 中创建新的密钥,或在 Azure、GCP 或 OCI 中创建新的密钥版本,并授予 OpenAI 读取权限。
  2. 注册新密钥或新版本。
  3. 为项目选择新的 extkey ID,并确认选择正确。

注册信息是注册时保存的固定快照,在云端轮换密钥不会更新快照。只要还有记录依赖旧私钥,就要保留旧私钥。为项目选择其他密钥不会迁移现有记录。

删除密钥

删除注册记录前,请先在每个使用该密钥的活跃项目中清除密钥选择或选择其他密钥:

curl --fail-with-body -sS -X DELETE "$KEYS_URL/$KEY_ID" \
  -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \
  -H "OpenAI-Organization: $ORG_ID"

删除成功后,API 会返回 HTTP 200,响应中包含 object: "organization.external_key.deleted"。此操作不会删除您的云端密钥。

故障排查

错误 排查方法
401 或 403 使用组织管理 API 密钥,并确认该密钥有权注册外部密钥。
400 external_key_provider_error 检查云端信任关系、读取权限和网络访问,并检查密钥是否已启用、所用算法是否正确。
400 请求验证错误 检查密钥用途、AWS 密钥本身的 ARN,以及 Azure、GCP 或 OCI 密钥的确切版本标识符。
OCI 密钥验证失败 检查密钥的 openai_organization_id 标签,确认密钥为 3072 位 RSA 密钥、已启用且属于指定保管库,并核实读取权限的授权范围是否限定为该保管库和该密钥。
404 检查注册 ID 和组织。已删除的注册记录和其他组织的注册记录均无法使用。
external_key_used_by_active_projects 在所有使用该密钥的活跃项目中清除密钥选择或选择其他密钥。
密钥不再匹配 注册新密钥或新版本,并选择其新的注册 ID。

联系支持团队时,请提供错误信息和 x-request-id。切勿分享凭据。

相关指南