載入中

程式碼執行與 Files API

第 46 課10 分鐘
載入中

Anthropic API 提供兩個配合使用效果絕佳的強大功能:Files API 與程式碼執行(Code Execution)。雖然乍看之下兩者似乎互不相干,但將它們結合起來,就能為委派複雜任務給 Claude 開啟一些非常有趣的可能性。

Files API

Files API 提供了另一種處理檔案上傳的方式。您不需要將圖片或 PDF 以 base64 資料的形式直接編碼在訊息中,而是可以事先上傳檔案,之後再參照它們。

我們的伺服器向 Claude 傳送原始圖片資料與文字「你在這張圖片中看到什麼?」,Claude 回覆「我看到一棵高大的樹」。

運作方式如下:

  • 使用另一個 API 呼叫,將您的檔案(圖片、PDF、文字等)上傳給 Claude
  • 收到一個包含唯一檔案 ID 的檔案中繼資料物件
  • 在之後的訊息中參照該檔案 ID,而非每次都附上原始檔案資料

我們的伺服器在圖片區塊中傳送檔案 ID,加上文字「你在這張圖片中看到什麼?」,Claude 回覆「我看到一棵高大的樹」。

當您想要多次參照同一個檔案,或是處理體積較大、每次請求都重新附上會很麻煩的檔案時,這種方式特別有用。

程式碼執行工具

程式碼執行是一種以伺服器為基礎的工具,不需要您自行提供實作。您只需在請求中加入預先定義好的工具結構描述(schema),Claude 就能視需要在一個隔離的 Docker 容器中執行 Python 程式碼。

我們的伺服器要求 Claude 計算圓周率到小數點後第 50 位;Claude 回傳程式碼、結果「3.1415926535」以及一段文字回答。

程式碼執行環境的主要特性:

  • 在隔離的 Docker 容器中執行
  • 沒有網路存取權限(無法呼叫外部 API)
  • Claude 可以在單一對話中多次執行程式碼
  • 結果會由 Claude 擷取並解讀,用於產生最終回應

結合 Files API 與程式碼執行

真正強大之處在於將這兩項功能結合使用。由於 Docker 容器沒有網路存取權限,Files API 就成為將資料帶進與帶出執行環境的主要方式。

以下列出的工作流程:一則包含容器上傳區塊與文字的使用者訊息,接著是 Claude 回覆的程式碼、結果與文字。

以下是典型的工作流程:

  1. 使用 Files API 上傳您的資料檔案(例如 CSV)
  2. 在訊息中加入包含該檔案 ID 的容器上傳區塊
  3. 要求 Claude 分析資料
  4. Claude 撰寫並執行程式碼來處理您的檔案
  5. Claude 可以產生輸出結果(例如圖表),供您下載

實際範例

讓我們來看一個使用串流服務資料的真實範例。這個 CSV 檔案包含使用者資訊,包括訂閱方案等級、觀看習慣,以及是否已流失(取消訂閱)。

streaming.csv 檔案,欄位包括 UserID、SubscriptionTier 和 TotalViewingHoursLastMonth,以及從 USER_00001 開始的資料列。

首先,使用一個輔助函式上傳檔案:

python
file_metadata = upload('streaming.csv')

然後建立一則訊息,同時包含已上傳的檔案與分析請求:

python
messages = []
add_user_message(
    messages,
    [
        {
            "type": "text",
            "text": """Run a detailed analysis to determine major drivers of churn.
            Your final output should include at least one detailed plot summarizing your findings."""
        },
        {"type": "container_upload", "file_id": file_metadata.id},
    ],
)

chat(
    messages,
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}]
)

了解回應內容

當 Claude 使用程式碼執行時,回應中會包含多種類型的區塊:

  • 文字區塊 - Claude 的分析與說明
  • 伺服器工具使用區塊 - Claude 決定執行的實際程式碼
  • 程式碼執行工具結果區塊 - 執行程式碼後的輸出結果

列印出的回應:一個關於流失驅動因素的文字區塊、一個程式碼匯入 pandas 的伺服器工具使用區塊,接著是一個工具結果。

Claude 可能會在單一回應中多次執行程式碼,逐步建構其分析。每個執行循環都包含程式碼及其結果。

下載產生的檔案

其中一項最強大的功能,是 Claude 能夠產生檔案(例如圖表或報告),並讓這些檔案可供下載。當 Claude 建立視覺化圖表時,它會被儲存在容器中,您可以使用 Files API 下載它。

請在回應中尋找 type: "bash_code_execution_output" 的區塊 —— 這些區塊包含所產生內容的檔案 ID:

python
download_file("file_id_from_response")

下載的多面板流失分析圖表:500 名使用者、38.6% 流失率、最主要的流失驅動因素為客戶服務互動。

結果是一份內容完整的分析報告,搭配專業的視覺化圖表,若以人工方式撰寫程式碼來產生,將會耗費相當大量的工夫。

不僅限於資料分析

雖然資料分析是一個自然而然的應用場景,但 Files API 與程式碼執行的結合開啟了許多其他可能性:

  • 影像處理與操作
  • 文件解析與轉換
  • 數學運算與建模
  • 客製化格式的報告產生

關鍵在於,您可以將複雜的運算任務委派給 Claude,同時透過 Files API 保有對輸入與輸出的掌控。這創造出一種強大的工作流程,讓 Claude 成為您的程式設計助手,能夠實際執行方案並進行迭代。