檔案與已發布的成品
檔案儲存在智慧體的環境中。成品是從 OpenAI 代管環境發布的檔案副本。環境到期後,你仍可下載這份副本。
| 環境 | 檔案擷取方式 |
|---|---|
self_hosted |
使用供應商的檔案 API 或已掛載的檔案系統。 |
openai_hosted |
使用工作階段的 Artifacts API 擷取 /workspace/outputs 下的檔案。 |
none |
環境沒有檔案系統。請從工作階段項目讀取輸出。 |
上傳檔案
如果使用 OpenAI 代管環境,請在建立工作階段時透過 environment.files 提供輸入檔案。每個檔案的目的路徑都必須位於 /workspace 下。
使用 type: "file_id" 時,請提供 file_id,其值可從 Files API 取得。使用 type: "inline" 時,請提供經過 base64 編碼的 data。兩種方式都必須指定 path。
若要在環境建立連線後新增檔案,請使用環境的 Files API。
排解上傳錯誤
建立工作階段或附加檔案時,檔案檢查可能會傳回 HTTP 429,並附上 files_api_rate_limit_exceeded 錯誤碼。如需瞭解回應內容與復原步驟,請參閱 Files API 速率限制。
若收到 HTTP 400,請查看 error.param 和 error.message,找出需要修正的輸入。例如,若目的路徑不在 /workspace 下,就會收到以下回應:
{
"error": {
"type": "invalid_request_error",
"code": "invalid_request_error",
"message": "path must be an absolute POSIX path inside /workspace",
"param": "path"
}
}
參數路徑對應到請求的結構。下表中的 i 是檔案索引,第一個檔案的索引為 0:
| 請求 | error.param 範例 |
|---|---|
| 在環境中新增一個檔案 | path、data 或 file_id |
| 建立工作階段或預熱環境 | environment.files[i].data |
| 建立或更新環境範本 | files[i].data |
請使用有效的 base64 資料與檔案 ID,並在 /workspace 下指定絕對路徑。請確認檔案符合檔案限制。若目的路徑經過符號連結、該路徑已存在,或路徑中任一部分的名稱過長,API 就會傳回 HTTP 400。
若安裝檔案時發生非預期錯誤,API 會傳回 HTTP 500。重試前,請先確認目的檔案是否已建立,再依照重試指引操作。
擷取檔案
從自有環境擷取
請智慧體將輸出寫入已知路徑。回合結束後,透過供應商或自有基礎設施擷取檔案。請在環境到期或刪除環境前,將檔案存入應用程式的儲存空間。
自行代管環境中的檔案不會透過 Artifacts API 發布,包括 /workspace/outputs 下的檔案。如需瞭解各供應商的檔案存取方式,請參閱沙盒供應商。
從 OpenAI 代管環境擷取
請智慧體將檔案儲存在 /workspace/outputs 下,例如 /workspace/outputs/report.pdf。回合結束時,OpenAI 會將輸出檔案發布為無法變更的成品。
請將 API 用戶端、工作階段 ID、已完成回合的 ID、成品路徑及本機目的路徑傳入以下函式。函式會列出成品,再下載回合與路徑皆相符的檔案:
# Pass the saved session ID, completed turn ID, artifact path, and local destination.
def download_artifact(client, session_id, turn_id, path, destination):
for artifact in client.beta.agents.sessions.artifacts.list(session_id):
if artifact.turn_id != turn_id or artifact.path != path:
continue
with client.beta.agents.sessions.artifacts.with_streaming_response.content(
artifact.id, session_id=session_id
) as response:
response.stream_to_file(destination)
return
raise FileNotFoundError(f"No artifact for {path!r} in turn {turn_id}")如需查閱請求與回應的欄位,請參閱列出成品、擷取中繼資料及下載內容的 API 參考文件。
下載多個檔案
此 API 每次請求只能下載一個成品,沒有批次下載端點。若要下載多個檔案,請先列出成品,再逐一請求每個檔案的 content。若要一次下載所有結果,請智慧體將結果打包成 ZIP 檔並存放在 /workspace/outputs 下,再將該壓縮檔當作單一成品下載。
檔案保存期限
環境到期後,已發布的成品仍會保留。請在刪除工作階段前下載所有需要保存的成品。
此 API 不支援上傳或編輯成品。若要發布新版本,請智慧體更新檔案並完成另一個回合。你可以根據回合 ID 和路徑區分各個版本。
不再需要已發布的副本時,即可刪除成品。刪除成品後,環境中的原始檔案仍會完整保留。
檔案限制
| 檔案操作 | 限制 |
|---|---|
| 建立工作階段時一併提供檔案 | 每次請求最多 50 個檔案。 |
| 內嵌上傳 | 每個檔案最多 5 MiB,以 base64 編碼前的大小計算。 |
| 在同一次建立請求中內嵌上傳檔案 | 總計最多 10 MiB,以 base64 編碼前的大小計算。 |
| 從 Files API 複製檔案 | 每個檔案最多 50 MiB。 |
| 發布成品 | 每個檔案最多 200 MiB。 |
| 同時發布多個輸出檔案 | 總計最多 500 MiB。 |