如需完整的文件索引,請參閱 llms.txt。在文件頁面的網址末尾加上 .md ,即可取得該頁面的 Markdown 版本。
主要導覽
主題

設定非對稱金鑰

向 OpenAI 註冊由雲端服務管理的公開金鑰

向 OpenAI 註冊由雲端供應商管理的 RSA-3072 非對稱金鑰組。

私密金鑰會留在 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

註冊時,系統會先驗證金鑰,再儲存註冊資料。成功時會傳回 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 列出這些非對稱金鑰的註冊資料。省略篩選條件會傳回所有用途的註冊資料,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"

刪除成功時會傳回 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 金鑰、已啟用且屬於指定的保存庫,並確認已授予 OpenAI 讀取該保存庫和金鑰的權限。
404 檢查註冊 ID 和組織。無法使用已刪除或屬於其他組織的註冊資料。
external_key_used_by_active_projects 在所有使用中的專案內清除金鑰選擇或改選其他金鑰。
金鑰不再相符 註冊替代金鑰,並選取其新的註冊 ID。

聯絡支援團隊時,請提供錯誤訊息和 x-request-id。切勿提供驗證憑證。

相關指南