Vork 使用手冊

文件類型
使用手冊
更新日期
閱讀時間
11 分

Vork 研究預覽的安裝與操作指南,涵蓋 JSON、TypeScript、Python 場景、渲染品質、輸出通道、Agent 迭代、GPU 限制、效能數據及商用授權。

來源
文件資訊
voyager-so/vork
授權
LicenseRef-vork-Preview

用場景程式驅動 3D 與 VFX 渲染,從首張預覽到輸出驗收。

原始碼版本
0.5.1研究預覽
場景編寫方式
3JSON、TypeScript、Python
內建品質設定
4previs、draft、final、path

01用途與架構

系統定位

Vork 是供 AI Agent 操作的無介面 3D 與 VFX 引擎。Agent 撰寫場景、執行渲染、檢查影像,再修改攝影機、材質或光源;操作入口是 CLI 與場景檔案。

引擎以 Rust 與 Slang 實作,使用 Vulkan 或 Metal。一般場景可直接寫 JSON,也可由 TypeScript 或 Python SDK 產生 JSON;自訂 GPU 程式可擴充材質、攝影機、運算與合成。

Agent 場景迭代流程
  1. 場景編寫

    • JSON
    • TypeScript SDK
    • Python SDK
  2. CLI 驗證與渲染

    • 場景檢查
    • 品質設定
    • GPU 執行
  3. 輸出驗收

    • 影像與影片
    • 控制通道
    • 警告與完成中繼資料

檢查影像與警告後,回到場景程式修改。

適用於程式化產品鏡頭、場景變體、動畫與實拍素材合成。專案仍處研究預覽;預設渲染採近似光照,任意 Blender 場景的外觀與穩定性需逐案驗證。

來源版本為 0.5.1,固定提交為 5de38c2f81edd6d3c1c19bb1ed5bb90547856301。範例未在本次研究中執行 GPU 渲染;效能數字採官方記錄,鳥群的 EEVEE 比較為推估值。

02平台、GPU 與安裝路徑

安裝與驗證

平台已確認需求影片依賴
macOSApple Silicon、macOS 26 以上、Metal;安裝腳本會拒絕舊版系統MP4 使用系統 VideoToolbox;解碼與部分備援需要 ffmpeg
Linuxx64、glibc 2.35 以上、GLIBCXX_3.4.30、支援硬體光線追蹤的 NVIDIA Vulkan 驅動MP4 封裝需要 ffmpeg
Windowsx64 Windows 10/11、支援硬體光線追蹤的 NVIDIA Vulkan 驅動MP4/MOV 需要 ffmpeg
  • 未完成:

    確認 GPU 支援光線查詢;AMD、Intel GPU 與 Intel Mac 不在支援範圍。

  • 未完成:

    NVIDIA A100、H100、H200、B200、B300 缺少所需硬體光線追蹤,不能只依型號新舊選購。

  • 未完成:

    TypeScript 編寫需要 Node 22.18 以上及 npm;Python 編寫需要 Python 3.11 以上。直接編寫 JSON 不需要這些語言執行環境。

  • 未完成:

    保留完整安裝目錄;執行檔旁的 Slang、OIDN、函式庫、SDK 與授權檔案都是套件的一部分。

macOS 與 Linux 安裝程式

Linux 需先備妥 NVIDIA 驅動。Ubuntu 的系統依賴命令如下;這段需要管理員權限。

bash
sudo apt-get update
sudo apt-get install -y ca-certificates curl tar libvulkan1 libgomp1 ffmpeg

macOS 與 Linux 使用同一支官方安裝程式。先下載並檢視腳本,再執行;腳本會驗證 SHA256SUMS、安裝至使用者目錄、執行設定並更新 shell 的 PATH。

bash
curl -fL https://github.com/voyager-so/vork/releases/latest/download/install.sh -o /tmp/vork-install.sh
sh /tmp/vork-install.sh
export PATH="$HOME/.local/bin:$PATH"
vork --version
vork help

Windows 安裝程式

先安裝 NVIDIA 驅動與 ffmpeg。使用 winget install Gyan.FFmpeg 後,開啟新的 PowerShell,再執行官方安裝程式。

powershell
$installer = Join-Path $env:TEMP 'vork-install.ps1'
Invoke-WebRequest -UseBasicParsing https://github.com/voyager-so/vork/releases/latest/download/install.ps1 -OutFile $installer
powershell -NoProfile -ExecutionPolicy Bypass -File $installer
$env:Path = "$env:LOCALAPPDATA\Programs\vork;$env:Path"
vork --version
vork help

npm 專案安裝

在具備 Node 22.18 以上與支援 GPU 的環境,也可採專案安裝。保留 npm 的 optional dependencies,它們提供平台執行套件。

bash
npm create vork@latest my-shot
cd my-shot
npx vork setup
npx vork render scene.json --out render.png

採 npm 專案安裝時,後續所有 vork 命令均需加上 npx 前綴,從專案目錄執行。

既有 npm 專案使用 npm install @voyager-so/vork。npm 上未加 scope 的 vork 是其他套件;主 README 將 pip 標為尚未提供,Python 子套件 README 則提供 pip SDK 說明。以下採完整安裝包內的 Python SDK,pip SDK 本身不包含渲染器。

03建立、檢查與重新產生場景

首張影像與 SDK

使用完整安裝程式後,建立僅使用內建幾何的起始專案。vork init 不需網路或 GPU,遇到將被覆寫的既有輸出檔案會拒絕建立。

bash
vork init my-shot
cd my-shot
vork check scene.json --profile std/previs
vork render scene.json --profile std/previs --out preview.png
vork render scene.json --profile std/final --out final.png

開啟 preview.png 檢查取景,再修改 scene.json 的顏色或攝影機位置。vork check 的成功訊息為 Scene checked successfully,但它不測試 GPU 記憶體容量或編碼器。

編寫方式建立命令修改後操作
JSONvork init my-shot直接渲染 scene.json
TypeScriptvork init my-ts-shot --language typescript依起始 README 安裝 SDK,執行 node scene.ts 重新產生 JSON
Pythonvork init my-py-shot --language python在虛擬環境安裝 SDK,執行 python scene.py 重新產生 JSON

完整安裝程式的 macOS/Linux SDK 安裝路徑如下。在自己的專案內執行,並讓原生 vork 位於 PATH。

bash
python3 -m venv .venv
. .venv/bin/activate
python -m pip install "$HOME/.local/lib/vork/python"
npm install "$HOME/.local/lib/vork/sdk"

Windows 的 SDK 位於 %LOCALAPPDATA%\Programs\vork\python 與 %LOCALAPPDATA%\Programs\vork\sdk;Python 原始碼可用 .venv\Scripts\python scene.py 執行。SDK 與引擎需使用同一發行版本;VORK_BIN 可指定執行檔。

04場景、動畫與 GPU 程式

核心能力

場景

vork help nodes --all

幾何與資產

使用內建形狀、網格與 glTF 資產。場景使用右手座標、Y 軸向上,距離單位為公尺;資產相對路徑以場景檔案為基準。

外觀

vork help materials --all

材質與光源

一般材質先使用內建 OpenPBR 輸入;需要特殊外觀時才撰寫 Slang。RGB 背景只改變攝影機看到的背景,不會照亮場景。

動畫

vork help animation --all

軌道與時間

動畫層可包含軌道或 glTF clip,支援 STEP、LINEAR 與 CUBICSPLINE。拓樸與程式碼在渲染期間固定;攝影機 target 不能直接動畫化,可指向具位移軌道的命名節點。

擴充

vork help programs --all

Slang 與模擬

公開介面涵蓋表面、位移、攝影機、環境、合成與 compute。模擬採固定時間步進,可從初始化或相容檢查點重播;複雜程式會增加首次編譯時間。

預設渲染結合光柵可見性與硬體光線追蹤光照,另提供路徑追蹤。場景解析、動畫軌道求值與檔案 IO 仍使用 CPU;GPU compute 不代表所有工作都在 GPU 執行。

05取景、光照與交付

渲染品質設定

設定預設取樣用途主要限制
std/previs依預覽策略取景、材質與直接光照省略間接反彈光,不能用來判定最終光照
std/draft4光照預覽近似間接光,預設 OIDN 去雜訊
std/final8預設交付近似間接光會省略部分反彈路徑
std/path64室內、玻璃與焦散有限反彈與取樣預算,通常較慢

使用 --set samples=32 可覆寫取樣,允許範圍為 1 到 4096。增加取樣不能補回 std/final 省略的光傳輸路徑;室內偏暗或光澤反彈不符預期時,改以 std/path 比較。

缺少快速 GPU 去雜訊器時,draft 與 final 會改用 16 與 32 次取樣且不去雜訊。--set denoise=true 可強制使用較慢的 CPU 去雜訊器,--set denoise=false 可關閉去雜訊。

vork setup 只預熱起始場景的 std/final,一般 GPU 著色器預熱上限為十分鐘;到期可成功結束並延後剩餘編譯,必要的 GPU 與工具檢查失敗則仍會報錯。vork setup --skip-warmup 只做必要檢查;vork setup --all 預熱內建程式與品質設定目錄,且沒有該時間上限。CPU 模式的預熱也沒有時間上限,新場景程式仍可能首次編譯數分鐘。

06影像、影片與控制通道

輸出與完成判定

輸出命名方式驗收條件
PNG 單張--out preview.png預設時間為起點;保留 Alpha
PNG 序列--out frames/使用目錄輸出,不能用 PNG 數字樣板檔名
OpenEXR 序列--out frames/%06d.exr多圖層、場景線性、預乘 Alpha;單張也要保留數字樣板
H.264 MP4--out clip.mp4每個合成影格的最終 Alpha 必須不透明
ProRes 4444 MOV--out clip.mov可保留最終 Alpha,編碼依平台而定

--channels 可選 color、depth、object_index、view_normal、motion、camera、shadow_catcher 與 aov:NAME。PNG 的部分控制通道會量化或截斷;需要場景線性浮點資料時使用 EXR,並依 vork help outputs 解讀各通道。

目錄輸出使用 meta.json,檔案輸出使用如 clip.mp4.meta.json 的附檔。影片也會輸出攝影機中繼資料;--diagnostics 另寫入時間記錄。

07迭代、路徑與驗收

Agent 操作原則

分開場景與品質

先用 previs 檢查構圖,再以 final 或 path 比較光照。記錄場景、品質設定與輸出路徑,避免用低品質預覽直接判定交付結果。

先檢查再渲染

使用與目標渲染相同的 profile 執行 check;需要可攜式著色器編譯檢查時加上 --shaders。check 不開啟 GPU,仍需要對應 Slang 工具鏈。

一併保存外部資源

SDK 可能把大型資料移至外部 buffer,儲存時也會移除舊 JSON 引用的過時產生檔。快照需複製 JSON 與所有引用資源,同一目的地的儲存與讀取需依序進行。

同時檢查影像與警告

成功渲染仍可能省略或替代部分效果。將 stderr、完成中繼資料、warnings 與畫面一起納入驗收,依被省略效果決定修改或退件。

交給 Agent 的任務應指定主體、鏡頭、輸出與完成條件。例如要求先建立起始場景、閱讀 vork help、產生預覽並檢查,確認攝影機與光照後才輸出最終品質;這是官方 README 的起步流程。

08官方場景與預期輸出

圓角方塊操作範例

將官方 README 的以下場景存為 scene.json。它使用內建幾何,不需下載外部模型;畫面包含藍色圓角方塊、地板、面光源與攝影機。

json
{"version":2,"nodes":[
  {"type":"mesh","geometry":{"std":"rounded_box","size":[2,2,2],"radius":0.3},
   "materials":[{"inputs":{"base_color":[0.12,0.35,0.65],"specular_roughness":0.3}}]},
  {"type":"mesh","translation":[0,-1.1,0],"geometry":{"std":"rounded_box","size":[10,0.2,10],"radius":0},
   "materials":[{"inputs":{"base_color":[0.35,0.35,0.35]}}]},
  {"type":"light","shape":"rectangle","translation":[-3,5,4],"target":[0,0,0],
   "energy":700,"size":4,"color":[1,0.92,0.8]},
  {"type":"camera","translation":[3,2,5],"target":[0,0,0]}
],"render":{"resolution":[640,480]}}

先檢查場景並渲染單張,再測試短片輸出。

bash
vork check scene.json --profile std/previs
vork render scene.json --profile std/previs --out preview.png
vork check scene.json --profile std/final
vork render scene.json --profile std/final --out final.png
vork render scene.json --profile std/final --frame-start 0 --frame-end 23 --out clip.mp4

需要動態鏡頭時,依 vork help animation --all 增加位移或旋轉軌道,再檢查開頭、中段與結尾。匯入 model.glb 時,改用 type: asset 與 file,保留同目錄的貼圖和 buffer,並依模型尺度調整取景。

09測量條件與比較邊界

官方效能數據

官方案例Vork 時間比較資料適用範圍
B-interior.json 最終短片59.231 秒EEVEE 107.026 秒240 影格、1920 × 1080、24 fps;不同取樣及品質
B-night.json 最終短片92.201 秒EEVEE 213.477 秒同組暖機後影片,不能視為等品質比較
百萬鳥群 skim96.942 秒同為 4 次取樣的 EEVEE 推估 773.7 到 1082.5 秒192 影格、1080p;EEVEE 只由局部影格外推
B-car-pan.json 路徑追蹤單張26.901 秒Cycles 4.632 秒沿用較早建置,Vork 較慢

最終品質與鳥群資料使用官方記錄的建置 81ae2b075 與 NVIDIA L4,並非本次來源提交重新測量。鳥群的設定與暖機另需 243.809 與 166.030 秒,合計至影片為 506.781 秒;資產準備與傳輸另計。

官方廣泛測試交付 583/585 張影像,百萬星點場景在兩種品質設定均記憶體不足。較早的 19 項品質比較未通過既定 FLIP 條件,未在該建置重做;細節、散焦與高光差異仍需目視比較。

10裝置、畫質與失敗條件

限制與故障處理

症狀原因或邊界處理方式
nvidia-smi 有 GPU,Vulkan 只有 llvmpipe容器可能無法載入 NVIDIA ICD檢查驅動發現機制,依官方遠端 GPU 文件修正
新場景長時間沒有第一張影像新程式或管線需冷編譯讀取進度,保留快取;升級或換驅動後重跑 setup
室內偏暗,增加取樣仍無改善final 省略部分光傳輸路徑使用 path 比較,檢查材質與光源
Mac 玻璃或密集透明場景中止Metal 的已知可靠性限制嘗試 path 或支援的 NVIDIA GPU,先測完整鏡頭;降低解析度不保證修復
需要煙霧或變動密度體積任意煙霧、網格密度與部分自訂組合尚不支援依 fog 規則使用均勻介質或合格高度霧,其他效果另行合成
輸出成功但效果不符部分效果以警告方式省略或替代檢查 stderr 與 warnings,不能只依退出碼驗收

Linux 可明確指定 vork setup --gpu cpu 與 vork render scene.json --gpu cpu --out frame.png,但 Mesa Vulkan 驅動仍需光線查詢與 storage buffer arrays。CPU 模式很慢,不會自動選用;Metal 沒有對應 CPU 模式。

退出碼類別下一步
0成功檢查本次中繼資料、警告與畫面
2用法錯誤檢查命令、旗標與輸出命名
3場景或程式無效修正 schema、資源或 Slang 程式
4裝置、GPU 記憶體、編碼器或設定依具體錯誤調整資源或環境
5檔案系統 IO檢查路徑、權限與儲存空間

影片遇到被拒絕的影格會停止;PNG/EXR 序列可繼續其他影格,但最後仍非成功退出,且不寫入完成用 meta.json。批次工作需保留退出狀態。

11研究預覽與商用邊界

授權與素材管理

Vork 採 LicenseRef-vork-Preview,提供原始碼,研究預覽期間可免費商用。此授權不屬開放原始碼授權,後續版本也可能採不同條款。

行為當前授權條件
組織內部渲染、交付客戶完成媒體允許
自用修改允許
分享未修改副本需保留授權與所有聲明
散布修改版本、販售或重新授權 Vork需事前書面許可
提供讓他人提交場景或工作的代管渲染服務需事前書面許可

產出的場景、程式碼與媒體不由 Vork 主張權利;匯入資產仍保留自己的條款。Blender bridge 是獨立的 GPL-3.0-or-later 元件;範例圖片、模型與實拍素材另有授權,使用時需保留相應出處。

Vork 會每日最多向 npm 查詢一次穩定版本更新,之後在 stderr 提示。需要關閉時設定 VORK_NO_UPDATE_NOTIFIER;這只影響更新檢查與提示。

12進階鏡頭與正式導入

後續操作

  1. 以內建幾何完成單張驗收,再加入自有 glTF 模型;先固定攝影機、資源路徑與輸出規格。

  2. 依 vork help outputs 建立深度、法線、物件索引與攝影機資料的下游流程,保存完成中繼資料。

  3. 在原始碼 checkout 中閱讀 examples/cake/、examples/vfx-artifact/、examples/murmuration/ 的準備方式與授權,再使用其素材。

  4. Blender 匯入採 bridge 的無介面命令,檢查 export-report.json 的替代與缺漏;其 OpenPBR 轉換不保證與 Blender 外觀一致。

bash
blender -b --disable-autoexec source.blend --python integrations/blender/export.py -- --out /tmp/vork-scene

沒有合適本機 GPU 時,可評估官方 Voyager 雲端渲染;本手冊未驗證其帳號、費率或配額。自行提供多人代管服務前,先確認 Preview License 的書面許可要求。

參考資料