跳至主要內容

畫布基礎

CodefyUI 是單頁應用程式，中央是畫布，左側是側邊欄，選取節點時右側會顯示設定面板，底部則是結果面板。本頁說明這些區域及其主要控制項。沒有開啟任何分頁時，除了工具列之外，這些區域都會換成歡迎畫面。

側邊欄​

左側邊欄是一列以圖示切換的分頁；本頁說明節點、圖表、範例與自訂與外掛。點擊目前分頁的圖示或按 Ctrl/Cmd+Shift+B，可將面板收合成圖示列。拖曳面板邊緣可將寬度設為 180 至 520 px，瀏覽器會在重新載入後保留此寬度。

  • 節點會依顏色標示的類別列出所有節點，並提供搜尋、全部展開、全部收合與類別捷徑。搜尋框會比對節點名稱、一行說明、較長的詳細說明，以及外掛節點所屬外掛的名稱；在中文介面下，也會比對中文的說明與詳細說明。搜尋結果的順序是：名稱完全相同、名稱以搜尋文字開頭、名稱中有單字以它開頭（split 會找到 TrainTestSplit）、名稱含有它，最後才是只有其他欄位符合的節點。每個類別內依這個順序排列，最符合的類別排在最前面，因此名稱與你輸入的文字完全相同的節點會排在最前面。開啟顯示節點說明時，游標停在節點上會顯示它的說明；外掛節點的說明卡片最後一行是來自外掛：，後面接外掛名稱（外掛中心的目錄載入前顯示外掛 id）。需要選用套件包的節點會顯示需要套件標籤。你可以先放置這些節點，但套件尚未安裝時，執行會失敗並指出所需套件。節點分類下方的預設組合分類會列出可拖曳到畫布的可重用節點群組，搜尋框也會比對它們的名稱、說明與標籤。請參閱節點參考與預設組合。
  • 圖表會列出伺服器上已儲存的圖，最近修改的排在前面，並可搜尋。點擊一列會開啟那個圖，並把它所在的分頁綁定到這個檔案，之後按「儲存」就直接覆寫它。目前分頁是空的、也沒有可復原的步驟時，圖會放進目前分頁，否則會開在新分頁，所以不會取代任何圖；已經開著的圖則是把它的分頁切到前面，不會再開一份。該列的選單只有重新命名與刪除。標題列可將目前的圖另存新檔並重新整理清單。底部的匯入... 可讀取圖的 .json（除非目前分頁是空的，否則會開在新分頁），或 .cduiworkspace 工作區檔案（會新增分頁）。請參閱分頁與持久化。
  • 範例會列出範例圖。點擊範例可將它插入目前畫布，或拖曳範例以選擇放置位置。請參閱範例集。
  • 自訂與外掛提供自訂節點 → 管理...、選用套件 → 套件中心... 與外掛 → 外掛中心...。請參閱外掛中心。已安裝的外掛包會將 foundations:Edu-KNN 等使用命名空間的節點加入節點分頁。

節點分類模式設定（設定 → 編輯器）決定節點分頁列出多少節點。預設的全部會列出 16 個類別中的全部 158 個內建節點。入門只列出 Data、CNN、Training 與 IO 四個類別，以及歸在這些類別下的預設組合。其他類別都會隱藏，包括每個可執行的圖都需要的 Start 節點所在的 Control，以及 Utility（Print、Reshape）與 Tensor Operations（Softmax）。快速搜尋不受這個設定影響：不論哪種模式，都可以在畫布上雙擊來新增任何節點。

畫布​

  • 新增節點。 從側邊欄拖曳節點，或在畫布上雙擊以開啟快速搜尋，再輸入節點或預設組合名稱。快速搜尋比對節點與預設組合時，使用的欄位與排列順序都和節點分頁的搜尋相同，兩者合成一份清單，最多列出 20 筆結果（搜尋框空白時 Start 排在第一個），預設組合會標上預設徽章，選取的節點會放在你雙擊的位置。
  • 選取節點。 點擊節點，或使用 Shift+點擊選取多個節點。按住 Shift 並在空白畫布拖曳可框選；不按 Shift 拖曳則會平移畫布。
  • 移動檢視。 捲動滑鼠滾輪可縮放，最小到 10%。左下角的按鈕依序是放大、縮小、讓整張圖符合視窗，以及鎖定畫布（鎖定後節點無法移動、連線或選取）。在右下角的小地圖上拖曳可以平移檢視範圍，在上面捲動則會縮放。每個分頁在頁面開著的期間會保留各自的平移與縮放；重新載入後，檢視範圍會重新符合整張圖。
  • 複製與貼上。 Ctrl/Cmd+C 會複製選取的節點、它們之間的連線，以及其中收合子圖的定義；連到選取範圍外節點的連線不會被複製。Ctrl/Cmd+V 會貼到目前的分頁：複本會取得新的 id，放在原位置往右下各 50 px，並呈選取狀態，復原一次即可移除。剪貼簿屬於編輯器，不是系統的剪貼簿，所以可以把節點帶到其他分頁，但無法帶到另一個瀏覽器視窗，而且重新載入後就會清空。節點右鍵選單中的複製只會複製那一個節點與它的參數，不含連線。
  • 開啟節點詳情。 雙擊節點，或選取節點後按 Enter。節點詳情會顯示參數、連接埠與說明。執行後還會顯示錄製的輸出與統計。
  • 套用自動排版。 按 Shift+L 將圖由左至右排列，並讓檢視範圍符合排版結果。排版會將 skip connection 繞過的管線區段放在該連線下方。這會讓 U-Net 呈 U 形、將 residual block 的節點放在 bypass 連線下方，並讓簡單鏈維持單一直線。預設的排版實驗只排列含有 Start 節點的連通節點群組。工具列的自動排版選單也提供排版全部與排版選取。Shift+L 會重複上次選擇的模式。未綁定的註記會留在原位。

所有快捷鍵請見 快捷鍵。

連線​

  • 建立連線。 從輸出連接埠拖曳到輸入連接埠。每個連接埠都有明確的資料型別，例如 Tensor、Model、Dataset、DataLoader、Optimizer、Loss、Scalar、String、Image、List、Transform 或 Trigger。不相容的放置會被拒絕。已經存在的同一條連線不會再加一次。一個輸入只接一個來源：把連線放到已經有連線的輸入上，會取代原本那條，按一次復原就能還原。一個輸出則可以接到任意多個輸入。要在多個來源之間選擇，請把它們接到 Switch。舊版存的圖可能仍有接了多條連線的輸入，以前執行時會取檔案中最後一條。現在 Run、匯出與存成預設組合都會拒絕這種圖。開啟這種圖時會出現帶有插入 Switch的提示，Run 對每個這類輸入的拒絕訊息也有插入 Switch：這些連線會依檔案順序接到一個新的 Switch，selector 指向最後一條，因此圖的計算結果與之前相同。
  • 拆下或重新連接連線。 以滑鼠左鍵拖曳已連接的輸入連接埠。將連線放到另一個連接埠可重新連接，放到空白處則會刪除。刪除前會顯示紅色圓環。拖曳時按住 Shift、Ctrl 或 Alt，則會從這個輸入開始拉一條新連線；放到某個輸出上時，會取代這個輸入原本的連線。Start 節點的 trigger 連線也以同樣方式移動：拖曳它在所觸發卡片左上角的端點，放到新卡片的任何位置即可。拖曳期間，它離開的那張卡片會以紅框標示。
  • 檢視連線值。 執行後點擊連線，可查看該連線所傳值的型別、shape、dtype、min、max 與 mean。查看統計會開啟該節點的統計分頁。
  • 變更連線樣式。 在設定 → 編輯器中，選擇預設的電路板走線或平滑曲線。這個樣式會套用到所有連線，包括從 Start 節點拉出的虛線 Trigger 連線。

註記​

在空白畫布上按右鍵，並選擇新增文字註記或新增圖片註記。雙擊文字註記可編輯內容；按 Esc 或點擊其他地方會結束編輯並保留文字。點擊空白的圖片註記可上傳圖片，雙擊圖片註記則可更換圖片；CodefyUI 會將圖片縮小至最多 800 px，並儲存在圖中。註記的右鍵選單提供綁定到最近的節點、解除綁定、更改顏色（Yellow、Blue、Green、Red、Purple 或 Gray）與刪除。已綁定的註記會以一條線連至節點，並在自動排版時跟著節點移動。未綁定的註記會留在原位，通知會指出它未被重新定位。

節點卡片​

節點卡片會列出節點的連接埠與參數。被 visible_when 規則隱藏的參數不會列出；其餘的基本參數一律列出，進階參數則只有在值與預設值不同時才會列出。機密值會顯示為 ••••••••，程式碼參數則顯示前四行，後面接還有 N 行。拖曳連線時，可接受這條連線的輸入連接埠會亮起，其他的則會變暗。

執行期間與執行後，卡片的外框顏色與底部狀態列會顯示節點狀態：執行中...、已完成、已快取、已跳過、未選取（Switch 沒有選到它所在的分支），或是錯誤： 加上錯誤訊息，游標停在上面可看到完整內容。TrainingLoop 卡片只會在每個 epoch 結束後短暫以輪次、損失與進度條取代執行中...；結果面板的訓練分頁會即時顯示訓練進度。TextGenerate、HFTextGenerate 或 LLMChat 產生文字時，底部狀態列會以文字的最後三行取代執行中...，嵌入節點則顯示目前已嵌入幾段文字；完成後的完整文字在節點的輸出中，不會留在卡片上。已完成的 ModelSaver 或 CheckpointSaver 卡片還會多一個顯示存檔檔名的按鈕，點擊即可下載該檔案。被略過的節點會顯示略過徽章。缺少選用套件包的節點會顯示需套件徽章；參數目前選的值需要尚未安裝的套件或模型時，值旁邊會顯示需套件。

工具列​

工具列由左至右包含以下控制項：執行與停止（執行期間執行會顯示執行中... 並停用，停止只在這時可用）；此圖的裝置選單，第一個選項（預設為跟隨設定（CPU））使用「設定」中選的裝置，其他選項則把這台伺服器的某個裝置指定給這張圖，並存進圖檔（請參閱 GPU 與裝置設定）；儲存圖示，會把目前分頁寫回它開啟時的那個圖，只有在分頁還沒綁定任何圖時才會詢問名稱；檔案（儲存、另存新檔... 與清除畫布）；匯出（匯出為 JSON、匯出架構圖 (SVG)、匯出架構圖 (PNG)、匯出為子圖、匯出為 Python，以及分隔線下方的工作區 (.cduiworkspace)，它會把所有開啟的分頁寫進一個工作區檔案）；範例圖庫；重新載入節點；自訂節點；自動排版及其模式選單；狀態指示點（目前分頁的閒置、執行中、已完成或錯誤）；已安裝外掛新增的控制項；設定；顯示快捷鍵清單的 ?；字級控制項（小、預設、大）；以及語言控制項（English、繁體中文；第一次開啟時依瀏覽器的語言決定）。在專案模式下，logo 旁的徽章會顯示目前開啟的專案名稱。沒有開啟任何分頁時，只會留下這個徽章、設定、?、字級與語言。儲存、載入與匯出方式請參閱 分頁與持久化。

設定面板​

選取節點後，右側面板會顯示其參數。面板在節點名稱下方顯示一行摘要，較長的說明放在名稱旁的 ? 裡；每個參數的說明與允許範圍則放在參數名稱右側的 ? 裡。把滑鼠移到 ? 上、用鍵盤聚焦，或點一下即可閱讀。後端定義會決定參數元件，包括整數、浮點數、文字、布林值、下拉選單（select）、模型、圖片與資料檔案選擇器、內嵌的張量格狀編輯器、遮蔽顯示的機密欄位，以及會檢查腳本 import 的程式碼編輯器（請參閱 PythonScript 節點）。具有 visible_when 規則的參數，只有在相關選項符合其中一個指定值時才會顯示。

基本參數會直接顯示。其他參數位於預設收合的進階區段，其標題會顯示隱藏的參數數量。進階參數會儲存在圖中、包含在 Python 匯出結果內，且處理方式與基本參數相同。

系統會先套用條件顯示規則，再計算進階參數數量。例如，Optimizer 使用 SGD 時，數量不會包含 Adam 的 betas，因為該參數不適用。規則可以列出多個接受值，因此九種優化器中有四種共用的參數，會在這四種優化器下顯示。

設定面板與節點詳情使用相同的表單元件，因此會顯示相同的參數控制項。

檔案選擇器會列出伺服器上已有的檔案。旁邊的三個按鈕分別用來從你的電腦上傳檔案並選取它、下載選取的檔案，以及重新讀取清單。模型選擇器接受 .pt、.pth、.safetensors、.ckpt 與 .bin；圖片選擇器接受 .png、.jpg、.jpeg、.bmp、.webp、.gif 與 .tiff；資料選擇器接受 .csv、.tsv、.txt 與 .json。機密欄位的值不會寫進已儲存的圖、匯出檔或瀏覽器的自動儲存，所以只在這次工作階段有效。

張量格狀編輯器的大小取決於節點的 shape（TensorInput）或 kernel_size（Conv2dExplicit）。在 TensorInput 上，只有 value_mode 為 explicit 時才能編輯。填 0、填 1 與隨機（-1 到 1 之間的值）會填滿所有格子；超過二維的張量會顯示 dim 選單，用來選擇畫面上顯示的二維切片；超過 512 格的張量無法在格狀編輯器中編輯。形狀改變時，已存的數值會依原順序保留，不足的補 0，多出的捨去。

結果面板​

底部面板有多個分頁，並可調整大小或收合：

  • 執行紀錄會列出目前分頁這次執行回報的內容，每個事件一筆並附上時間：執行的開始與結束、每個節點的結果（執行中或使用快取的節點不會新增一筆）、節點寫出的文字（Print 與 PythonScript 中 print() 的輸出，以及 ModelSaver、CheckpointLoader、TrainingLoop 等節點的說明訊息），以及直接畫在紀錄裡的圖片、圖表與影片。文字會保留換行與空白，印出的表格會保持欄位對齊。每次按執行都會從空白的紀錄開始。分頁上的數字是紀錄的筆數。
  • 訓練會顯示 TrainingLoop 提供的即時 loss 曲線與 epoch 表格，包括 loss、delta 與 time；上方還有目前的輪次、最新的損失、最佳損失與進度條。TrainingLoop 開始並回報設定前，此分頁會停用；回報後會自動選取（執行任務分頁開啟時除外），epoch 列則在每個 epoch 完成時加入。分頁上的數字是 epoch 數。
  • 執行任務會列出伺服器擁有的執行，包括排隊中、執行中與已完成的狀態。分頁上的數字是伺服器上執行中與排隊中的執行數量。請參閱執行佇列。

已安裝的外掛可以新增其他分頁。清除會清空目前分頁的紀錄，訓練分頁的圖表也會一併清空；執行任務分頁與外掛的分頁不會顯示這個按鈕。

節點執行失敗時，它在執行紀錄中的那一行會列出錯誤。幾種常見的錯誤會改寫成說明該怎麼修改的句子：

  • 缺少輸入：「請把 tensor 輸入接到這個節點。」或『請接上必要的輸入「…」。』
  • Linear 層的 in_features 與輸入不符：「尺寸不符：這一層收到 … 個特徵，但它設定的是 … 個。」
  • reshape 的目標形狀與 tensor 不合：「無法變形成 …」
  • 卷積層的輸入通道數不對：「通道數不符：…」
  • 節點需要的選用套件包尚未安裝：「這個節點需要 … 套件，請到套件中心安裝。」

ValueError 會去掉類別名稱後顯示，其他錯誤則照節點拋出的內容顯示。執行任務面板中的錯誤文字也會套用相同的改寫。點擊錯誤那一行，可在下方展開詳情，並保留訊息原本的換行。節點那一行上的短 id（節點 id 的前八個字元）點下去會在畫布上選取該節點。

Start 節點驅動執行​

每個可執行的圖都需要至少一個 Start 節點。將其 Trigger 輸出（以菱形連接點顯示）連至第一個要執行的節點。可執行集合包含每個由 Trigger 連線直接指定的節點、其下游資料流、向該集合供應資料的所有上游節點，以及每個已到達的預設組合或子圖容器內部的根節點。圖中沒有 Start 連線時，執行會拒絕該圖，並顯示要求新增及連接 Start 節點的錯誤。詳情請參閱 你的第一個圖。

設定 popover​

工具列的設定 popover 最上方是新手指引：按開始後會一次框出畫面上的一個主要區域，並附上簡短說明。用下一步、上一步或方向鍵切換，按 Esc 或 × 離開；畫面上沒有的區域（例如沒有選取節點時的節點面板）會自動略過。設定名稱旁的 ? 會說明該設定的作用。其下的控制項分成以下區段：執行、LLM 提供者、選用套件與外掛（套件中心 與 外掛中心）、錄製與檢視、訓練行為、編輯器，以及這台伺服器。其中錄製與檢視與訓練行為屬於目前分頁的圖，只有開啟分頁時才會出現。各區段的設定列見設定 popover 的開關；其中的錄製與梯度控制項會決定 教學檢視器 可以顯示的資料。

通知​

訊息會出現在右下角，每則都有關閉按鈕。錯誤訊息會一直留到你關閉為止；提示開啟中的圖表在磁碟上已變更的警告（帶有重新載入按鈕）也是如此。其他訊息都會在四秒後自動關閉，包括帶有開啟套件中心或開啟外掛中心按鈕的訊息。

以下訊息回報與執行伺服器的連線，以及執行的狀態：

  • 「連線中斷 — 嘗試重新連線中…」：連線中斷，通常是因為伺服器停止或重新啟動。編輯器會在 1 秒後重試，接著等 2 秒、4 秒，依此類推，每次最多等 30 秒。
  • 「已重新連線」：連線已恢復，原本在追蹤某次執行的分頁會重新接上它。
  • 「無法重新連線至執行伺服器」：重試十次都失敗。請重新啟動伺服器，再重新載入頁面。
  • 「圖太大，無法傳送 — …」：伺服器拒收超過 WebSocket 訊息上限的圖，並關閉了連線。請簡化圖，或調高 CODEFYUI_WS_MAX_MESSAGE_BYTES（請參閱把 graph 當成函式呼叫）。
  • 「已重新連上仍在執行中的工作」：重新載入頁面後，某個分頁的執行仍在伺服器上進行，該分頁會重新接上它。
  • 「這次執行沒有啟動 — …」：伺服器拒絕了這次執行，執行紀錄中的那一行最後會附上伺服器提供的原因。原因可能是已有兩個 interactive 執行正在進行（不論來自哪個分頁；上限為 CODEFYUI_RUN_INTERACTIVE_MAX_CONCURRENT，請參閱執行佇列），或是這個分頁的上一次執行還在進行。前者的情況下，分頁會回到閒置：等某個執行結束後再按一次執行，或在執行任務面板中用停止結束其中一個。後者的情況下，分頁會維持執行中...，按停止即可停止那次執行。
  • 「伺服器停止或重新啟動，這次執行因此中斷。」：伺服器停止時執行就會結束，重新啟動也不會接續。分頁會回到閒置（若是重新啟動，則在重新連上之後），原本仍在執行的節點卡片不再顯示執行中...，執行任務面板也會把這次執行列為已中斷。按執行即可重新開始。
  • 「伺服器確認這次執行之前，連線就中斷了。…」：按下執行之後、伺服器回應之前，連線就中斷了。分頁會回到閒置；可在執行任務面板查看這次執行是否已啟動。