系統定位
Vork 是供 AI Agent 操作的無介面 3D 與 VFX 引擎。Agent 撰寫場景、執行渲染、檢查影像,再修改攝影機、材質或光源;操作入口是 CLI 與場景檔案。
引擎以 Rust 與 Slang 實作,使用 Vulkan 或 Metal。一般場景可直接寫 JSON,也可由 TypeScript 或 Python SDK 產生 JSON;自訂 GPU 程式可擴充材質、攝影機、運算與合成。
場景編寫
- JSON
- TypeScript SDK
- Python SDK
CLI 驗證與渲染
- 場景檢查
- 品質設定
- GPU 執行
輸出驗收
- 影像與影片
- 控制通道
- 警告與完成中繼資料
檢查影像與警告後,回到場景程式修改。
適用於程式化產品鏡頭、場景變體、動畫與實拍素材合成。專案仍處研究預覽;預設渲染採近似光照,任意 Blender 場景的外觀與穩定性需逐案驗證。
來源版本為 0.5.1,固定提交為 5de38c2f81edd6d3c1c19bb1ed5bb90547856301。範例未在本次研究中執行 GPU 渲染;效能數字採官方記錄,鳥群的 EEVEE 比較為推估值。
安裝與驗證
| 平台 | 已確認需求 | 影片依賴 |
|---|---|---|
| macOS | Apple Silicon、macOS 26 以上、Metal;安裝腳本會拒絕舊版系統 | MP4 使用系統 VideoToolbox;解碼與部分備援需要 ffmpeg |
| Linux | x64、glibc 2.35 以上、GLIBCXX_3.4.30、支援硬體光線追蹤的 NVIDIA Vulkan 驅動 | MP4 封裝需要 ffmpeg |
| Windows | x64 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 的系統依賴命令如下;這段需要管理員權限。
sudo apt-get update
sudo apt-get install -y ca-certificates curl tar libvulkan1 libgomp1 ffmpegmacOS 與 Linux 使用同一支官方安裝程式。先下載並檢視腳本,再執行;腳本會驗證 SHA256SUMS、安裝至使用者目錄、執行設定並更新 shell 的 PATH。
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 helpWindows 安裝程式
先安裝 NVIDIA 驅動與 ffmpeg。使用 winget install Gyan.FFmpeg 後,開啟新的 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 helpnpm 專案安裝
在具備 Node 22.18 以上與支援 GPU 的環境,也可採專案安裝。保留 npm 的 optional dependencies,它們提供平台執行套件。
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 本身不包含渲染器。
首張影像與 SDK
使用完整安裝程式後,建立僅使用內建幾何的起始專案。vork init 不需網路或 GPU,遇到將被覆寫的既有輸出檔案會拒絕建立。
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 記憶體容量或編碼器。
| 編寫方式 | 建立命令 | 修改後操作 |
|---|---|---|
| JSON | vork init my-shot | 直接渲染 scene.json |
| TypeScript | vork init my-ts-shot --language typescript | 依起始 README 安裝 SDK,執行 node scene.ts 重新產生 JSON |
| Python | vork init my-py-shot --language python | 在虛擬環境安裝 SDK,執行 python scene.py 重新產生 JSON |
完整安裝程式的 macOS/Linux SDK 安裝路徑如下。在自己的專案內執行,並讓原生 vork 位於 PATH。
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 可指定執行檔。
核心能力
場景
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 執行。
渲染品質設定
| 設定 | 預設取樣 | 用途 | 主要限制 |
|---|---|---|---|
std/previs | 依預覽策略 | 取景、材質與直接光照 | 省略間接反彈光,不能用來判定最終光照 |
std/draft | 4 | 光照預覽 | 近似間接光,預設 OIDN 去雜訊 |
std/final | 8 | 預設交付 | 近似間接光會省略部分反彈路徑 |
std/path | 64 | 室內、玻璃與焦散 | 有限反彈與取樣預算,通常較慢 |
使用 --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 模式的預熱也沒有時間上限,新場景程式仍可能首次編譯數分鐘。
輸出與完成判定
| 輸出 | 命名方式 | 驗收條件 |
|---|---|---|
| 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 另寫入時間記錄。
Agent 操作原則
分開場景與品質
先用 previs 檢查構圖,再以 final 或 path 比較光照。記錄場景、品質設定與輸出路徑,避免用低品質預覽直接判定交付結果。
先檢查再渲染
使用與目標渲染相同的 profile 執行 check;需要可攜式著色器編譯檢查時加上 --shaders。check 不開啟 GPU,仍需要對應 Slang 工具鏈。
一併保存外部資源
SDK 可能把大型資料移至外部 buffer,儲存時也會移除舊 JSON 引用的過時產生檔。快照需複製 JSON 與所有引用資源,同一目的地的儲存與讀取需依序進行。
同時檢查影像與警告
成功渲染仍可能省略或替代部分效果。將 stderr、完成中繼資料、warnings 與畫面一起納入驗收,依被省略效果決定修改或退件。
交給 Agent 的任務應指定主體、鏡頭、輸出與完成條件。例如要求先建立起始場景、閱讀 vork help、產生預覽並檢查,確認攝影機與光照後才輸出最終品質;這是官方 README 的起步流程。
圓角方塊操作範例
將官方 README 的以下場景存為 scene.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]}}先檢查場景並渲染單張,再測試短片輸出。
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,並依模型尺度調整取景。
官方效能數據
| 官方案例 | Vork 時間 | 比較資料 | 適用範圍 |
|---|---|---|---|
B-interior.json 最終短片 | 59.231 秒 | EEVEE 107.026 秒 | 240 影格、1920 × 1080、24 fps;不同取樣及品質 |
B-night.json 最終短片 | 92.201 秒 | EEVEE 213.477 秒 | 同組暖機後影片,不能視為等品質比較 |
| 百萬鳥群 skim | 96.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 條件,未在該建置重做;細節、散焦與高光差異仍需目視比較。
限制與故障處理
| 症狀 | 原因或邊界 | 處理方式 |
|---|---|---|
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。批次工作需保留退出狀態。
授權與素材管理
Vork 採 LicenseRef-vork-Preview,提供原始碼,研究預覽期間可免費商用。此授權不屬開放原始碼授權,後續版本也可能採不同條款。
| 行為 | 當前授權條件 |
|---|---|
| 組織內部渲染、交付客戶完成媒體 | 允許 |
| 自用修改 | 允許 |
| 分享未修改副本 | 需保留授權與所有聲明 |
| 散布修改版本、販售或重新授權 Vork | 需事前書面許可 |
| 提供讓他人提交場景或工作的代管渲染服務 | 需事前書面許可 |
產出的場景、程式碼與媒體不由 Vork 主張權利;匯入資產仍保留自己的條款。Blender bridge 是獨立的 GPL-3.0-or-later 元件;範例圖片、模型與實拍素材另有授權,使用時需保留相應出處。
Vork 會每日最多向 npm 查詢一次穩定版本更新,之後在 stderr 提示。需要關閉時設定 VORK_NO_UPDATE_NOTIFIER;這只影響更新檢查與提示。
後續操作
以內建幾何完成單張驗收,再加入自有 glTF 模型;先固定攝影機、資源路徑與輸出規格。
依
vork help outputs建立深度、法線、物件索引與攝影機資料的下游流程,保存完成中繼資料。在原始碼 checkout 中閱讀
examples/cake/、examples/vfx-artifact/、examples/murmuration/的準備方式與授權,再使用其素材。Blender 匯入採 bridge 的無介面命令,檢查
export-report.json的替代與缺漏;其 OpenPBR 轉換不保證與 Blender 外觀一致。
blender -b --disable-autoexec source.blend --python integrations/blender/export.py -- --out /tmp/vork-scene沒有合適本機 GPU 時,可評估官方 Voyager 雲端渲染;本手冊未驗證其帳號、費率或配額。自行提供多人代管服務前,先確認 Preview License 的書面許可要求。