跳至主要内容

環境變數

本頁彙總了執行階段、建構工具和 SDK 工具所使用的環境變數。其中許多變數是除錯/診斷開關；大多數使用者可以忽略它們，除非需要進行疑難排解。

如需完整的已偵測清單，請參閱 環境變數清單。

注意：有些控制旋鈕是內部使用的或僅供測試，而且可能會變更。這些旋鈕已在此檔案中列出。 因為它們目前會出現在程式碼執行路徑中。

SDK 網路存取​

在 Palette SDK 3.0 或更新版本中，sima-cli sdk setup 會在容器環境中設定 CODE_SERVER_PASSWORD。再次執行 neat 即可查看密碼，並在 code-server 提示時輸入。URL 不包含密碼或權杖。neat --json 會新增包含 backend、auth、password、localUrl 和 remoteUrl 的 codeUI；請將此輸出視為含有認證資訊的資料。SDK 連接埠對應中的公開連接埠 codeUIHttps.host 優先於容器連接埠。

此行為依已安裝的 code-server 執行檔選擇；僅設定 CODE_SERVER_PASSWORD 不會改變舊版 OpenVSCode 的行為。CODE_SERVER_HTTPS_PORT 和 CODE_SERVER_WORKSPACE 優先於對應的舊版變數。設定 CODE_SERVER_WITHOUT_PASSWORD=1 時會回報 auth: "none" 並省略密碼值。舊版 OpenVSCode 映像仍使用權杖 URL。

  • NFS_SERVER_HOST_IP=<address> — 用於建構遠端連線的 SDK 主機位址。 Insight 和瀏覽器中的 VS Code URL。這通常由 sima-cli sdk setup 提供。
  • CONTAINER_HOST_IP=<address> — 舊版備援方案，用於取得遠端主機的位址。 當 NFS_SERVER_HOST_IP 主機無法使用時。
  • OPENVSCODE_SERVER_HTTPS_PORT=<port> — 用於瀏覽器版 VS Code 的 HTTPS 連接埠。 如果未設定， neat 不會顯示 VS Code 的網址。
  • OPENVSCODE_SERVER_TOKEN=<token> — 以瀏覽器為基礎的 VS Code 存取權杖。 sima-cli 產生的值是 URL 安全的。請將包含此值的 URL 視為憑證，切勿分享。
  • OPENVSCODE_WORKSPACE=<path> — 由瀏覽器開啟的 VS Code 工作區 （預設 /workspace）。
  • OPENVSCODE_SERVER_WITHOUT_TOKEN=1 — 啟動並宣傳基於瀏覽器的 VS Code。 在沒有使用驗證令牌的情況下。僅在受信任的本地環境中使用；切勿在服務可以從不受信任的網路存取時啟用此功能。

統一的偵錯設定檔（建議採用）​

  • SIMA_DEBUG_PROFILE=<components> — 統一的除錯啟用開關，用於常見的診斷功能。
    • 元件：pipeline、graph、gst、appsink、inputstream 或 all。
    • 多個元件可以用逗號或空格分隔（例如 pipeline,gst,inputstream）。
  • SIMA_DEBUG_LEVEL=<0..3> — 統一設定所使用的除錯詳細程度（預設值為 1）。
    • 0：已停用
    • 1：核心除錯日誌
    • 2：詳細的診斷資訊／緩衝區層級的追蹤資訊
    • 3：最高程度的詳細程度

舊有的逐變數除錯開關仍然有效，並且在明確設定時會覆寫預設設定檔。

核心建置/執行​

  • SIMA_PIPELINE_STRING_DEBUG=1 ——在建置時印出最終的 gst-launch 字串。
  • SIMA_PIPELINE_STATE_DEBUG=1 — 額外的狀態變更日誌。
  • SIMA_PIPELINE_TEARDOWN_DEBUG=1 — 記錄管線關閉步驟。
  • SIMA_PIPELINE_DRAIN_BEFORE_TEARDOWN_MS=<ms> — 在關閉管線之前，允許的排空時間（預設值為 1500 毫秒）。
  • SIMA_PIPELINE_DRAIN_MIN_OUTPUTS=<n> — 在關閉管線之前，必須先處理掉的最小輸出數量（預設值為 1）。

GStreamer 初始化 + 抑制​

  • SIMA_ALLOW_GST_INIT=1 — 允許在已初始化時手動執行 gst_init。
  • SIMA_GST_SUPPRESS_JSON_WARNINGS=0/1 — 抑制 JSON 警告訊息（預設為 true）。
  • SIMA_GST_SUPPRESS_GOBJECT_ASSERTS=0/1 — 抑制 GLib 斷言日誌輸出（預設為啟用）。
  • SIMA_GST_SUPPRESS_DEVICE_LOGS=0/1 — 停用裝置日誌（預設為啟用）。

GStreamer 超時時間​

  • SIMA_STATE_CHANGE_TIMEOUT_MS=<ms> — 管線狀態變更逾時時間（預設值為 15000 毫秒）。
  • SIMA_GST_TEARDOWN_TIMEOUT_MS=<ms> — 關閉逾時時間（預設值為 2000）。
  • SIMA_GST_TEARDOWN_REAPER_MS=<ms> — 關閉看門狗（預設值為 250）。
  • SIMA_GST_TEARDOWN_ASYNC=1 — 非同步清理。
  • SIMA_GST_POLL_SLICE_MS=<ms> — 用於應用程式接收器（app sink）拉取資料時的輪詢間隔（預設值為 200）。
  • 偏好的 API 設定選項：
    • ValidateOptions.preroll_timeout_ms — validate() 預先載入逾時。
    • RunOptions.input_timeout_ms — 輸入模式 Graph::run() 和支援的帶初始輸入建置預檢的輸出等待時間。
    • Run::run(..., timeout_ms) / Model::run(..., timeout_ms) — 各次呼叫的輸出等待時間；-1 表示無限等待，與 Run::pull(-1) 相同。
  • 舊版備援環境變數（僅在無法傳遞選項時使用）：
    • SIMA_GST_VALIDATE_TIMEOUT_MS=<ms> — validate() 超時時間（預設值為 2000/10000）。
    • SIMA_GST_RUN_INPUT_TIMEOUT_MS=<ms> — 上述 Graph::run()／預檢輸出等待的備援設定（預設為 10000）。

診斷工具與探測器​

  • SIMA_GST_DOT_DIR=<dir> — 輸出管線失敗或除錯時的 DOT 圖。
  • SIMA_GST_BOUNDARY_PROBES=1 — 連接邊界流量探頭。
  • SIMA_GST_STAGE_TIMINGS=1 — 階段時間探測。
  • SIMA_GST_ELEMENT_TIMINGS=1 — 元素計時探測。
  • SIMA_GST_FLOW_DEBUG=1 — 元素流程探測。
  • SIMA_GST_ENFORCE_NAMES=1 — 在建置時強制執行命名規則。
  • SIMA_GST_OPTIONS_DEBUG=1 — 在建置期間記錄 GStreamer 選項。
  • SIMA_GST_BUFFER_DEBUG_LIMIT=<n> — 限制緩衝區除錯列印的數量。
  • SIMA_GST_DETESS_INPUT_DEBUG=1 — detess 輸入除錯。
  • SIMA_GST_DETESS_OUTPUT_DEBUG=1 — detess 輸出除錯。
  • SIMA_GST_DETESS_POOL_DEBUG=1 — detess 資源池除錯。
  • SIMA_GST_APPSINK_BUFFER_DEBUG=1 — appsink 緩衝區除錯。
  • SIMA_GST_ALL_BUFFER_DEBUG=1 — 詳細的緩衝區除錯資訊。
  • SIMA_GST_RUN_INSERT_BOUNDARIES=1 ——在 run() 函數執行期間插入邊界。
  • SIMA_GST_VALIDATE_INSERT_BOUNDARIES=1 ——在 validate() 過程中插入邊界。

分派器／執行階段​

  • SIMA_DISPATCHER_TRACE=1 — 追蹤分派器步驟。
  • SIMA_ASYNC_TPUT_DIAG=1 — 非同步吞吐量診斷。
  • SIMA_ASYNC_WARMUP=<n> — 非同步預熱幀。
  • SIMA_PERF_POWER=1 — 在效能測試情境中啟用從 Sentinel 擷取板子電力資料。
  • SIMA_PERF_POWER_INTERVAL_MS=<ms> — 已棄用且會被忽略；Sentinel 每 2 秒取樣一次。
  • SIMA_PULL_TIMEOUT_DIAG=0/1 — 報告拉取逾時的情況（預設為啟用）。
  • SIMA_STAGE_DEBUG=1 — StageRun 除錯日誌。

輸入串流 / 範例除錯​

  • SIMA_INPUTSTREAM_DEBUG=1 ——詳細的 InputStream 日誌。
  • SIMA_INPUTSTREAM_WARN=1 ——關於 InputStream 事件的警告。
  • SIMA_INPUTSTREAM_POLL_MS=<ms> — 輸入串流輪詢間隔（預設值為 50 毫秒）。
  • SIMA_INPUTSTREAM_META_DEBUG=1 — 記錄 GstSimaMeta 的詳細資訊。
  • SIMA_INPUTSTREAM_ALLOC_DEBUG=1 — 設定除錯。
  • SIMA_INPUTSTREAM_PUSH_TIMING=1 — 推送時間記錄。
  • SIMA_INPUTSTREAM_PREFLIGHT_RUN=1 ——為 InputStream 進行預先測試。
  • SIMA_SAMPLE_DEBUG=1 — 記錄範例轉換。
  • SIMA_SAMPLE_BYTES=1 — 記錄樣本位元組大小。
  • SIMA_SAMPLE_FORCE_BUNDLE=1 — 強制產生套件輸出，用於除錯。
  • SIMA_NEAT_CAPS_TRACE=1 — 張量追蹤，用於推導張量上限。

預處理／偵測／接線​

  • SIMA_PREPROC_DEBUG_CONFIG=1 — 輸出預處理設定資訊。
  • SIMA_KEEP_DETESS_CONFIG=1 — 保留 detess 設定的輸出結果。
  • SIMA_DETESS_ASSERT_ON_ZERO=1 — 對 detess 輸出結果進行零值斷言。
  • SIMA_CLAMP_DETESS_NUM_BUFFERS=1 — 限制 detess 的緩衝區數量。
  • SIMA_DISABLE_SYNC_NUMBUFFERS_CVU_MLA=1 — 停用同步緩衝區數量限制。

模型（保留舊版環境變數名稱）​

  • SIMA_MLA_NEXT_CPU=<domain> — 覆寫 MLA 的 next_cpu。
  • SIMA_MPK_EXTRACT_ROOT=<dir> — 模型檔案的載入根目錄。會解析為絕對路徑。 路徑在每個程序中僅使用一次，因此重寫到提取的 JSON 中的路徑永遠不會依賴於工作目錄。權威性：如果無法寫入，則載入會失敗，而不是回退。如果未設定，則基礎路徑是已掛載的 NVMe 檔案系統中第一個可寫入的候選路徑，/data、TMPDIR，然後是工作目錄。NVMe 候選路徑必須是資料掛載上可寫入的 /dev/nvme* 區塊裝置：root、/boot、/efi 和其他系統掛載會被排除在外，vfat/ISO 檔案系統也會被排除。這些檢查適用於 NVMe 探索；/data、TMPDIR 和工作目錄回退保留其正常的檔案系統位置。NVMe 優先用於容量、可預測的位置以及避免對 eMMC 進行寫入。這並不是解碼速度的提升：此變數選擇輸出寫入的位置，而解碼是 CPU 密集型操作。

選擇的依據是可寫入性，而不是可用空間。.tar.gz 不限制其解壓縮後的大小，因此在解碼之前無法得知任何容量需求；空間會在解壓縮時以及從資訊清單中提取之前，針對每個區塊進行強制執行。因此，符合條件的 NVMe 將無條件地使用，如果沒有足夠的空間，則載入會失敗，並顯示 output_storage_unavailable，而不是回退到 eMMC。該檔案系統上的可用空間，或者 SIMA_MPK_EXTRACT_ROOT 指向其他位置，是解決方案。

  • SIMA_MPK_CLEANUP_EXTRACTED=0/1 — 在正常退出時，刪除每個程序提取的模型檔案資料（預設為 1）。 啟用清理功能時，每個程序都會將內容解壓縮到各自唯一且有鎖定保護的 proc_run_* 目錄中，並在程序結束時刪除該目錄。如果停用清理功能，則會保留該程序目錄以供檢查，並且不會將其納入過時目錄的垃圾回收機制中。該目錄不會被自動發現或由其他程序重複使用；當不再需要時，請手動刪除它。

Model 也可以接受一個已經組織好的套件根目錄，其中包含 etc、lib 和 share。該目錄將直接使用，無需解壓縮或複製；調用者擁有該目錄的生命週期，並且在使用模型時必須保持其不變。由 tar -xzf 產生的扁平目錄不是一個組織好的套件，因此不能直接使用。

  • SIMA_MPK_EXTRACT_GC_STALE_PROC=0/1 — 啟動時使用擁有權鎖定來移除已無人使用的 proc_run_* 解壓縮根目錄（預設為 1）。 舊版 proc_<pid> 根目錄必須在確認無人使用後手動移除。
  • SIMA_MODEL_TAR=<path> — 範例/測試所使用的基本模型套件路徑。 針對特定模型的覆寫設定（例如 SIMA_RESNET50_TAR、SIMA_YOLO_TAR 等）仍然優先生效。
  • SIMA_MPK_EXTRACT_MIN_FREE_BYTES=<bytes> — 在準備和 正在解壓縮模型封存檔（預設為 16 MiB）。
  • TMPDIR=<dir>——僅被視為上述基礎的後期候選方案，並直接用於。 由不選擇自己基礎版本的呼叫者進行暫存。模型載入不再在此處獨立進行暫存：解壓縮的快照和解壓縮的套件會共用選取的基礎版本。每次載入（包括僅檢查中繼資料的載入）都會將 .tar.gz 解壓縮一次到一個私有目錄中。在解壓縮期間，該檔案系統需要有足夠的空間來容納解壓縮的快照、套件以及 SIMA_MPK_EXTRACT_MIN_FREE_BYTES；150 MB 的參考套件的快照大約為 354 MB。請使用本機檔案系統——如果無法讀取可用空間，載入將會失敗，而網路掛載在斷開連接時會發生這種情況。載入完成後，無論成功還是失敗，都會刪除暫存目錄；如果發生意外終止或電源中斷，可能會留下一個暫存目錄。

由 SIMA_MPK_EXTRACT_MIN_FREE_BYTES 設定的可用空間保留量是一種盡力而為的機制。它會在解壓縮期間針對每個區塊，與檔案系統報告的可用空間進行檢查，因此，不相關的並行寫入器仍然可能在檢查之間耗盡檔案系統；然後載入將會失敗，並顯示已寫入的位元組數以及它正在使用的路徑。

RTSP / H264​

  • SIMA_H264_SDP_DUMP=<path> — 將 H264 SDP 轉儲到檔案中。
  • SIMA_H264_SPS_FIXUP_STREAM=<path> — 修正資料流中的 SPS。

測試／內部鉤子​

  • SIMA_TENSOR_MAPFAIL_DEBUG=1 — 記錄張量映射失敗的情況。

核心中繼資料驗證​

ProcessCVU 階段預設透過 Runtime 的 neatkernelrunner 執行。 沒有任何建置選項或環境變數可選擇舊的 ProcessCVU 外掛程式。

  • SIMA_CORE_COMPACT_METADATA=1 — 在能力協議完成後，允許於具擁有權的 runner 直連 appsink 邊界使用精簡 TensorSet 與具型別的目前影格中繼資料。 不可存在不相容的邊界、偵錯或流程觀察器。標準的具擁有權階段／元件計時仍然啟用， 並支援兩種表示法。無法表示的擴充仍保留舊式動態中繼資料。

不要將只支援舊式格式的探查掛到精簡邊界上。未達成能力協議時，Runtime 會為未知 使用者與觀察器保留舊式中繼資料；執行仍使用 neatkernelrunner。 此中繼資料選項不保證延遲或吞吐量。

套件與每週驗證（僅供測試）​

  • SIMA_TEST_PACKAGE_INVENTORY=<absolute-path> — 由 tools/ci/verify_core_dist.py --write-package-inventory 根據選定且已驗證的 發行封存檔產生的預期套件控制資料與負載身分。已安裝 DevKit 的套件清單測試需要它。 它不會將 dpkg 重新導向私用前綴，也不是安裝結果報告。
  • SIMA_TEST_PLATFORM_BASELINE=<absolute-path> — 使用 tools/ci/verify_core_dist.py --capture-platform-baseline 在安裝前擷取的 原生平台套件存在／不存在狀態、套件身分與 OTA 可用性／身分。已安裝 DevKit 的 套件清單測試需要它與所選套件清單。不要從安裝後狀態重新產生此基準。
  • SIMA_RUN_MNIST_PREPROC_CHANNELS1=1 — 選擇執行長時間 MNIST 前處理準確度測試。 請在測試固定資料驗證後，從 tools/ci/prepare_weekly_fixtures.py 取得此值， 而不是只為避免略過而手動設定。本機啟動程式使用 --environment-json； CI 則透過 --github-env 使用相同的對應資料。

測試固定資料群組選擇與已安裝套件設定組合，請參閱 測試需求。

PCIe 主機與卡片狀態​

NEAT_PCIE_SSH_USER 指定卡片的 SSH 使用者（預設為 sima）。NEAT_PCIE_SSH_KEY 指定私密金鑰（預設為 ~/.ssh/sima_neat_pcie_ed25519），也可繼續使用既有 SSH 設定與代理程式驗證。--offline 會略過網際網路更新檢查，但仍透過本機 SSH 讀取已連接的卡片。PCIe 主機狀態不檢查成品更新；請使用 sima-cli neat install core/pciehost/<distro>/<arch>@<ref> 更新主機套件。neat update 不會更新 PCIe 卡片。