開始前:準備帳號與預期成果
這篇教學會讓你請 dot 建立一份 CPU Notebook,分析 100 筆合成銷售資料,取得兩份 CSV、一張圖與已執行的 .ipynb,最後釋放本次 runtime。已有私人部署的使用者可跳到第 3 步。
- 可使用 dot,以及私人 ChatGPT Sites/Sites Plugin 的帳號;功能可用性依帳號而異。
- 你自己的 Google Colab 帳號、Google Cloud 專案與 OAuth Web client。
- 首次部署需能執行 Node.js 22.13+、npm 與 uv/Python 3.12 的環境;可請具 Sites 工具的 agent 協助。
此處使用完全合成資料,不需上傳個人檔案。程式會在你自己的 Colab 帳號執行,適用該帳號的資源與額度規則。
1. 建立自己的私人後端
GitHub Pages 是你正在閱讀的教學網站。實際 Notebook 後端需另外部署到一個只有你能存取的 ChatGPT Site。
把以下要求交給具 Sites 能力的 agent:
請讀取 https://github.com/KaiQin04/chatgpt-colab-plugin、其中的 AGENTS.md、docs/DEPLOYMENT.md、docs/OAUTH.md 與 skills/setup/SKILL.md。依當前安裝的 Sites skill,將 v0.3.5 原始碼部署到新建、僅本人可存取的 Site,使用我自己的 Google OAuth client,並協助連接它的私人 Plugin。憑證由我在設定介面輸入,Google 授權由我在瀏覽器完成。先完成不配置 Colab runtime 的檢查,不更動既有 Site。
本篇以 v0.3.5 為例。手動取得原始碼可使用以下命令:
git clone https://github.com/KaiQin04/chatgpt-colab-plugin.git
cd chatgpt-colab-plugin
git switch --detach v0.3.5Agent 應以此版本為模板建立新的 Site,套用資料庫 migrations,設定實際部署識別,並查核擁有者及 audience 僅包含你。完成 owner-only 查核後才設定 OWNER_PRIVATE_DEPLOYMENT_CONFIRMED=true。詳細命令、綁定與建置步驟見部署指南。
若帳號無法建立私人 Site,先處理 Sites 存取資格。
2. 設定 Google OAuth 並授權
- 在自己的 Google Cloud 專案開啟 Google Auth Platform,設定 Branding 與 Audience。個人測試可使用 External/Testing,將自己的 Google 帳號加入 test users。
- 依OAuth 指南設定
openid、https://www.googleapis.com/auth/userinfo.email、https://www.googleapis.com/auth/colaboratory。 - 建立 Web application client,將部署設定腳本輸出的 redirect URI 原樣加入。它的路徑應為
/oauth/google/callback,網域必須是你自己的 Site。 - 在 Site 設定介面填入
GOOGLE_CLIENT_ID、GOOGLE_CLIENT_SECRET與TOKEN_ENCRYPTION_KEY。加密金鑰依部署指南在自己的終端產生,直接填入 secrets 介面。 - 完成私人部署後,以擁有者身分開啟 Site,點選 Google 授權連結,在瀏覽器確認應用程式名稱、帳號與要求範圍後同意。
Client secret、token 與加密金鑰都不要貼到對話或 Git。Google 登入需由你本人完成。若使用 Testing 模式,refresh token 可能需要定期重新授權;詳細條件與正式發布要求見 OAuth 指南。
3. 連接 Plugin,確認 dot 能使用工具
安裝或連接 Sites 為這個私人部署建立的 Plugin。若找不到連線,請具 Sites 工具的 agent 讀取 get_site(include_mcp_connection: true),再用回傳的 Plugin ID 顯示連接介面。
OpenAI 說明 dot 可在授權範圍內使用既有 Plugin 連線。實際仍需確認你這個 dot 能看到本 Plugin 的工具;詳見官方權限說明。
請檢查我已連接的 Colab Plugin 是否提供 Notebook 工具。讀取 runtime 套件設定、Colab 運算狀態與現有 Notebook,先不要配置 runtime、安裝套件或執行程式。回報連線狀態、可用機型,以及是否有尚未釋放的既有任務。
對應工具是 get_runtime_settings 與 get_compute_status。若 dot 看不到工具,先修正 Plugin 連線、Google 授權或權限設定。
4. 請 dot 執行第一份分析
請使用我的 Colab Plugin 建立一個 CPU Notebook,用固定亂數種子產生 100 筆合成銷售資料,彙總各產品營收並畫長條圖。把 sales.csv、summary.csv 和 revenue.png 存到 outputs,匯出 Notebook 給我,完成後釋放這次的 runtime。
請 dot 將程式與結果保留在 Notebook 中。資料欄位可以使用 product、quantity、unit_price 與 revenue,產品使用合成分類 A、B、C。請它先檢查所需套件,必要時再在本次 runtime 準備。
可再補充以下重現與驗算要求:
亂數種子固定為 42。每筆 revenue = quantity × unit_price,依 product 加總 revenue;檢查各產品加總與原始資料總營收一致,並確認有 100 筆、無缺失值。圖表標籤使用英文。
dot 應建立 Notebook、寫入 cell、提交執行並輪詢結果。若你修改 cell,可在編輯器按 Shift+Enter。
5. 檢查並下載結果
在 Notebook 顯示執行完成後,請 dot 確認輸出已保存,匯出 Notebook 並提供可用的檔案下載方式。
| 檔案 | 驗收方式 |
|---|---|
sales.csv | 100 筆合成資料;欄位與型別符合分析要求。 |
summary.csv | 每個產品的營收彙總;加總等於原始總營收。 |
revenue.png | 可以開啟,標籤清楚,數值與 summary.csv 一致。 |
*.ipynb | 可以用 Notebook 工具開啟,包含程式、亂數種子與對應的執行輸出。 |
檔案應寫入本 Notebook 工作目錄下的 outputs/,讓 Plugin 保存成品。對應流程會使用 get_notebook、get_artifacts 與 export_ipynb。下載後打開確認即可。
6. 釋放本次 runtime 並核對
確認成品已保存且下載後,請 dot 使用 close_notebook 關閉本次 Notebook 的 runtime,再讀回運算狀態確認該 runtime 已釋放。
確認檔案都拿到後,釋放這次的 runtime。
若檔案還沒存好,先別關閉。
遇到問題時
- dot 找不到 Colab 工具
- 確認私人 Plugin 已連接,且目前的 dot 具備工具權限。沒有工具時,先完成連線,再提出執行要求。
- Google 顯示 redirect_uri_mismatch
- 比對 OAuth Web client 與部署設定腳本輸出的完整 redirect URI,包括 scheme、網域及 callback 路徑。
- 授權過期或失效
- 從自己的私人 Site 重新授權,並查看 OAuth 指南的 Testing 模式說明。不要手動複製 refresh token。
- 開機配置回傳 503
- 若配置 POST 在取得 runtime endpoint 前回傳 HTTP 503,該 Notebook 的開機嘗試會結束,狀態回到 closed。如需重新開機,請使用新的 idempotencyKey;若使用相同 key,則會讀回原本的結果。這類失敗紀錄會與已開機及未確認的 runtime 分開計數,並保留診斷資料。結束開機嘗試不代表 Google 已確認釋放 runtime。
- 執行逾時或結果不明
- 可查看原 Notebook 的狀態,或另開 Notebook 繼續工作。新 Notebook 會獨立配置,不會自動終止原 runtime。
- 下載失敗或找不到產物
- 確認檔案位於工作目錄的 outputs 資料夾、執行已完成且成品已保存。runtime 尚在時先處理保存問題,再重新取得下載連結。
這次 CPU 流程驗證完成後,才逐步加入自己的資料或 GPU 工作。需要 GPU 時請 dot 先查機型與需求;上傳可識別個人的資料前,先去識別化。