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

檔案與成品

從環境擷取檔案,並保存已發布的輸出檔案。

檔案與已發布的成品

檔案儲存在智慧體的環境中。成品是從 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。