.torchxconfig¶

狀態：測試版

您可以將專案的排程器執行設定檔（執行設定）儲存在 .torchxconfig 檔案中。目前，僅當從 CLI 執行元件時，才會讀取並遵循此檔案。

CLI 用法¶

排程器設定

cd 進入您要放置 .torchxconfig 檔案的目錄。CLI 只會從目前工作目錄 (CWD) 中提取 .torchxconfig 檔案，因此請選擇您通常從中執行 torchx 的目錄。通常這是專案目錄的根目錄。

透過執行以下指令產生設定檔

$ torchx configure -s <comma,delimited,scheduler,names>

# -- or for all registered schedulers --
$ torchx configure

如果您指定了 -s local_cwd,kubernetes，您應該會看到如下所示的 .torchxconfig 檔案

$ cat .torchxconfig
[local_cwd]

[kubernetes]
queue = #FIXME:(str) Volcano queue to schedule job in

.torchxconfig 採用 INI 格式，區段名稱對應於排程器名稱。每個區段都包含排程器的執行設定檔，格式為 $key = $value 鍵值對。您可能會發現某些排程器有空白區段，這表示排程器為其所有執行設定檔定義了合理的預設值，因此在執行時不需要任何執行設定檔。如果您想覆寫預設值，可以新增它們。**提示：**若要查看排程器的所有執行選項，請使用 torchx runopts <scheduler_name>。
具有 FIXME 預留位置的區段是排程器所需的執行設定檔。請將這些預留位置替換為適用於您的值。
**重要：**如果您對排程器為特定執行設定檔提供的預設值感到滿意，則**不應**在 .torchxconfig 中以相同的預設值重複指定它們。這是因為排程器可能會在日後決定變更預設值，這將導致您使用過時的預設值。
現在，您可以執行元件，而不必每次都指定排程器執行設定檔。只要確保您執行 torchx cli 的目錄實際上有 .torchxconfig 檔案即可！
```
$ ls .torchxconfig
.torchxconfig

$ torchx run -s local_cwd ./my_component.py:train
```
此外，也可以指定在執行時載入 .torchxconfig 以外的其他設定檔。要求是透過環境變數 TORCHX_CONFIG 指定設定檔路徑。它還會停用從多個目錄載入設定檔的階層結構，否則會發生這種情況。
使用者層級 .torchxconfig 除了專案目錄根目錄下的專案層級 .torchxconfig 之外，您還可以在 $HOME/.torchxconfig 中建立一個檔案，以覆寫或指定其他預設設定。此設定檔將會覆蓋在專案根目錄定義的設定檔。
設定選項的優先順序如下（從高到低）：
1. 直接從 CLI 指定的選項
2. 如果設定了 TORCHXCONFIG 環境變數，則為該檔案中指定的選項
3. 如果未設定 TORCHXCONFIG 環境變數，則為：
  
  使用者層級 .torchxconfig ($HOME/.torchxconfig) 中指定的選項
  
  .torchxconfig 中指定的選項
4. 程式碼中的任何預設值
請注意，格式錯誤或無法辨識的選項將會被略過，不會套用

元件設定

您可以透過新增以 component: 為首碼的區段來指定元件預設值。

[component:dist.ddp]
j=2x8
cpu=4

現在，當您執行 dist.ddp 元件時，這些設定檔會自動被提取。

$ torchx run -s local_cwd dist.ddp
... runs with -j 2x8 --cpu 4

CLI 子命令設定

可以覆寫 torchx 子命令的預設參數。任何 --foo FOO 參數都可以透過對應的 [cli:<cmd>] 設定區塊來設定。

對於 run 命令，您還可以設定 component 來設定要執行的預設元件。

[cli:run]
component=dist.ddp
scheduler=local_docker
workspace=file://some_workspace

程式化用法¶

與 cli 不同，如果您使用 torchx.runner.Runner 以程式化方式執行元件，則**不會**自動從 CWD 中提取 .torchxconfig 檔案。您必須手動指定包含 .torchxconfig 的目錄。

以下是一個範例

from torchx.runner import get_runner
from torchx.runner.config import apply
import torchx.specs as specs

def my_component(a: int) -> specs.AppDef:
   # <... component body omitted for brevity ...>
   pass

scheduler = "local_cwd"
cfg = {"log_dir": "/these/take/outmost/precedence"}

apply(scheduler, cfg, dirs=["/home/bob"])  # looks for /home/bob/.torchxconfig
get_runner().run(my_component(1), scheduler, cfg)

您也可以指定多個目錄（以優先順序排列），這在您想要將個人設定覆蓋在專案定義的預設值之上時非常有用。

設定 API 函式¶

torchx.runner.config.apply(scheduler: str, cfg: Dict[str, Optional[Union[str, int, float, bool, List[str], Dict[str, str]]]], dirs: Optional[List[str]] = None) → None[source]¶

依序從指定的目錄載入 .torchxconfig INI 檔案，並將排程器的執行設定套用至指定的 cfg。

如果沒有指定 dirs，則會在目前工作目錄中尋找 .torchxconfig。如果指定的目錄沒有 .torchxconfig，則會忽略該目錄。

請注意，指定的 cfg 中已存在的設定優先於設定檔中的設定，並且只會新增新的設定。對於以清單順序載入的設定也是如此。

例如，如果 cfg={"foo":"bar"} 且設定檔為

# dir_1/.torchxconfig
[local_cwd]
foo = baz
hello = world

# dir_2/.torchxconfig
[local_cwd]
hello = bob

則在呼叫方法後，cfg={"foo":"bar","hello":"world"}。

torchx.runner.config.load(scheduler: str, f: TextIO, cfg: Dict[str, Optional[Union[str, int, float, bool, List[str], Dict[str, str]]]]) → None[source]¶: 從指定的設定檔 f（.INI 格式）載入 [{scheduler}] 區段到提供的 runcfg 中，只會新增目前不在指定的 runcfg 中的設定（例如，不會覆寫 runcfg 中的現有值）。如果找不到區段，則不執行任何動作。

torchx.runner.config.dump(f: TextIO, schedulers: Optional[List[str]] = None, required_only: bool = False) → None[source]¶

將包含指定排程器名稱的 :py:class:torchx.specs.runopts 預設 INI 風格設定範本傾印至 f 指定的類檔案物件。如果沒有指定 schedulers，則會傾印所有已知的註冊排程器。

選用 runopt 會預先填入其預設值。必要的 runopt 會設定為 FIXME: ... 預留位置。若只想傾印必要的 runopt，請傳遞 required_only=True。

每個排程器的 runopt 都會寫入名為 [{scheduler_name}] 的區段中。

例如

[kubernetes]
namespace = default
queue = #FIXME (str)Volcano queue to schedule job in

引發:: ValueError – 如果指定的排程器名稱未知

torchx.runner.config.find_configs(dirs: Optional[Iterable[str]] = None) → List[str][source]¶

根據以下邏輯尋找並返回 .torchxconfig 檔案的路徑：

如果存在環境變數 TORCHXCONFIG，則會在單一元素清單中返回其值，並且不會搜尋透過 dirs 參數指定的目錄。
否則，會在 dirs 中尋找 .torchxconfig 檔案，並返回現有設定檔的路徑。如果未指定 dirs 或為空，則 dirs 預設為 [$HOME, $CWD]，其中 CWD 是當前工作目錄。

torchx.runner.config.get_configs(prefix: str, name: str, dirs: Optional[List[str]] = None) → Dict[str, str][source]¶

取得區段 ["{prefix}:{name}"] 中的所有設定值。如果區段不存在，則為空映射。

範例

# for config file:
# [foo:bar]
# baz = 1

get_configs(prefix="foo", name="bar") # returns {"baz": "1"}
get_config(prefix="foo", name="barr") # returns {}

torchx.runner.config.get_config(prefix: str, name: str, key: str, dirs: Optional[List[str]] = None) → Optional[str][source]¶

取得區段 ["{prefix}:{name}"] 中 key 的設定值。如果區段或金鑰不存在，則為 None。

範例

# for config file:
# [foo:bar]
# baz = 1

get_config(prefix="foo", name="bar", key="baz") == 1
get_config(prefix="foo", name="bar", key="bazz") == None
get_config(prefix="foo", name="barr", key="baz") == None
get_config(prefix="fooo", name="bar", key="baz") == None

torchx.runner.config.load_sections(prefix: str, dirs: Optional[List[str]] = None) → Dict[str, Dict[str, str]][source]¶

載入給定 .torchxconfig 檔案中以指定前綴開頭的區段內容。返回區段名稱（不含前綴）與載入到映射中的區段內容的映射映射。 ":" 用作前綴分隔符號。

以下顯示用於指定內建元件 dist.ddp 預設值的範例設定格式：

[component:dist.ddp]
j = 1x2
image = ghcr.io/foo:1

# calling `load_sections(prefix="component")` returns
#  {
#    "dist.ddp": {
#       "j":"1x2",
#       "image":"ghcr.io/foo:1",
#     },
#  }

區段中的金鑰必須與元件函數的參數名稱相符。以下範例顯示如何表示允許作為元件參數類型的各種類型。

[component:foo.bar]
int = 1
float = 1.2
bool = True # or False
str = foobar
list = a,b,c
map = A=B,C=D
vararg = -a b --c=d e

# to call the component as:
foo.bar(
   "-a", "b", "--c=d", "e",
   int=1,
   float=1.2,
   bool=True,
   str="foobar",
   list=["a", "b", "c"],
   map={"A":"B", "C": "D"})

.torchxconfig¶

CLI 用法¶

程式化用法¶

設定 API 函式¶

文件

教學課程

資源