---
title: "準備您的 model template"
description: "撰寫讓模型出現在 AI Model Center 的 ARX model template：collection 與 variant 結構、宣告模型本身的 model 區塊、模型的下載來源，以及服務它的推論引擎"
canonical_url: "https://developer.ardge.com/zh-tw/guide/model-provider/prepare-model-template"
---
# 準備您的 model template

> 撰寫讓模型出現在 AI Model Center 的 ARX model template：collection 與 variant 結構、宣告模型本身的 model 區塊、模型的下載來源，以及服務它的推論引擎

## 概觀

model template 是讓您的模型能夠部署在 ARX 上的關鍵。它是一組 YAML 目錄，宣告模型是什麼、權重從哪裡下載、運行需要多少資源，以及哪些推論引擎能夠服務它。

model template 一律是一組 **collection**（模型系列），即使只有一個 variant 也一樣。collection 是 marketplace 上的項目，每個 variant 則是同一系列中可獨立部署的建置。

本文說明該目錄的結構，並以宣告模型本身的 `model` 區塊為重點。

## 您將學到

- 規劃 collection 與 variant 目錄，並取用彼此一致的 id
- 在 `model` 區塊宣告模型資訊：參數量、格式、精度、任務類型與輸入輸出
- 以 `sources` 指向權重，並以 `deployment.engines` 指定服務它的引擎

## 適用版本

- ARX OS 1.0 以上

## 開始之前

- 您的模型已發布在 ARX 能下載的位置——Hugging Face 或 ModelScope repository，或其他您能指名的來源
- 若模型是 GGUF 建置，您已掌握要下載的精確檔名

<note>

**下載 skills**：套件為 [arx-isv-skills-v0.6.4.zip](https://developer.ardge.com/skills/arx-isv-skills-v0.6.4.zip)（約 185 KB）——解壓後將裡面的資料夾複製到您專案的 `.claude/skills/`。

</note>

<tip>

**交由 AI Agent 代為撰寫**：將 skills 套件指給您的 AI Agent，讓它依模型的來源頁面產生 template。

</tip>

## 目錄結構

template 直接放在 `templates/` 底下。collection 的目錄名稱即為它的 id，每個 variant 各有自己的子目錄：

```text
templates/
- publisher.yaml
- models.your-model/
  - collection.yaml         # collection 的根檔案
  - icon.svg                # 選用
  - localization.yaml       # collection 層級的翻譯（選用）
  - 0.6b-gguf/              # 每個 variant 一個目錄
    - manifest.yaml
    - localization.yaml     # 選用
  - 8b-instruct/
    - manifest.yaml
```

variant 目錄請以尺寸與建置方式命名——`0.6b-gguf`、`4b`、`8b-instruct`、`270m`——因為這個名稱會成為 variant id 的 `@variant` 後綴。

以下三個值敘述的是同一個系列，彼此不一致時驗證會失敗：

```yaml
# collection.yaml
id: models.your-model

# 0.6b-gguf/manifest.yaml
id: models.your-model@0.6b-gguf   # '@' 左側即 collection id
model:
  collection: your-model          # id 的最後一段，不帶前綴
```

<warning>

**兩份文件，兩個 version 常數**：`collection.yaml` 用 `version: "1"`，variant manifest 用 `version: "1.0"`。在 collection 裡寫成 `"1.0"` 是整個格式中最常見的第一個錯誤。

</warning>

## collection.yaml 的內容

collection 是這個模型系列在 marketplace 上的項目。除 `icon` 外，以下欄位皆為必填。

<table>
<thead>
  <tr>
    <th>
      欄位
    </th>
    
    <th>
      內容
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        metadata.id
      </code>
      
       / <code>
        name
      </code>
    </td>
    
    <td>
      系列 id（與目錄同名、不含 <code>
        @variant
      </code>
      
      ）與顯示名稱
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        metadata.description
      </code>
    </td>
    
    <td>
      這個系列是什麼、擅長什麼——可以是描述文字本身，也可以是 <code>
        collection.yaml
      </code>
      
       旁一個檔案的檔名，由該檔案存放內容
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        metadata.categories
      </code>
    </td>
    
    <td>
      封閉列舉，至少一項：<code>
        llm
      </code>
      
      、<code>
        embedding-model
      </code>
      
      、<code>
        reranker-model
      </code>
      
      、<code>
        image-model
      </code>
      
      、<code>
        audio-model
      </code>
      
      、<code>
        video-model
      </code>
      
      、<code>
        multimodal
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        metadata.tasks
      </code>
      
       / <code>
        inputTypes
      </code>
      
       / <code>
        outputTypes
      </code>
    </td>
    
    <td>
      與 variant 相同的三組封閉列舉，見 <a href="#model-">
        model 區塊
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        metadata.tags
      </code>
      
       / <code>
        license
      </code>
      
       / <code>
        developer
      </code>
      
       / <code>
        updateDate
      </code>
    </td>
    
    <td>
      自由標籤、授權條款、上游開發者名稱與網址，以及項目最後更新日期
    </td>
  </tr>
</tbody>
</table>

collection 沒有 `subtitle`——variant 才有。

## variant manifest.yaml 的內容

<table>
<thead>
  <tr>
    <th>
      區塊
    </th>
    
    <th>
      內容
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        metadata
      </code>
    </td>
    
    <td>
      id、名稱、版本、發布日期、<code>
        type: models
      </code>
      
      、分類、subtitle、開發者、支援語言與標籤。與 app manifest 不同，<code>
        subtitle
      </code>
      
       在這裡是必填
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        metadata.model
      </code>
    </td>
    
    <td>
      模型本身是什麼——本文的重點區塊
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        resources
      </code>
    </td>
    
    <td>
      該 variant 服務時所需的 CPU、記憶體、儲存空間、GPU 數量與 VRAM
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        deployment
      </code>
    </td>
    
    <td>
      <code>
        type: model
      </code>
      
      ，以及能夠服務它的引擎
    </td>
  </tr>
</tbody>
</table>

`metadata.releaseDate` 請填模型真正的發布日期，取自其來源頁面，而非您撰寫 manifest 的當天。`metadata.supportedLanguages` 指的是模型本身支援的語言，不是這份 template 翻譯成的語言。

## model 區塊

其中必填的是 `collection`、`params`、`format` 與 `sources`。其餘欄位雖為選用，但通常值得宣告——應用程式的依賴條件會依這些欄位篩選，未宣告的 variant 無法被比對到。

```yaml
model:
  collection: your-model           # collection 名稱，不帶前綴
  params: "0.6b"                   # ^[0-9]+(\.[0-9]+)?(b|m)$
  variant: reranker
  quantization: "Q8_0"
  format: gguf
  tasks:
    - text-ranking
  inputTypes:
    - text
  outputTypes:
    - score
  sources:
    - provider: huggingface
      modelId: ggml-org/Qwen3-Reranker-0.6B-Q8_0-GGUF
      files:
        - "qwen3-reranker-0.6b-q8_0.gguf"
```

### params

純參數量：數字、選用的小數點，以及小寫的 `b`（billion）或 `m`（million）。`"0.6b"` 與 `"270m"` 正確；`"8B"` 與 `"8b-gguf"` 錯誤——建置資訊屬於 variant id。若是 MoE 模型，請填**總**參數量，並在 subtitle 或 tags 中說明 active 參數。

### format

封閉列舉，且它決定哪些引擎能服務這個模型：

<table>
<thead>
  <tr>
    <th>
      值
    </th>
    
    <th>
      由誰服務
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        gguf
      </code>
    </td>
    
    <td>
      llama.cpp
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        safetensors
      </code>
    </td>
    
    <td>
      vLLM 與其他 Hugging Face Transformers 型態的 runtime
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        ct2
      </code>
    </td>
    
    <td>
      CTranslate2（faster-whisper）
    </td>
  </tr>
</tbody>
</table>

### variant、precision、quantization

- `variant`——`base`、`instruct`、`instruction-tuned`、`chat`、`embedding`、`reranker` 或 `transcription`
- `precision`——`fp32`、`fp16`、`bf16`、`fp8`、`int8` 或 `int4`。GGUF 建置請省略（量化方式已經說明了精度），safetensors 與 ct2 則要填寫
- `quantization`——自由字串，例如 `"Q8_0"`、`"Q4_K_M"`、`"awq"`，或 `null`

### tasks、inputTypes、outputTypes

三組封閉列舉，與 collection 宣告的相同：

<table>
<thead>
  <tr>
    <th>
      類型
    </th>
    
    <th>
      <code>
        tasks
      </code>
    </th>
    
    <th>
      <code>
        inputTypes
      </code>
    </th>
    
    <th>
      <code>
        outputTypes
      </code>
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      LLM
    </td>
    
    <td>
      <code>
        text-generation
      </code>
    </td>
    
    <td>
      <code>
        text
      </code>
    </td>
    
    <td>
      <code>
        text
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Embedding
    </td>
    
    <td>
      <code>
        text-embedding
      </code>
    </td>
    
    <td>
      <code>
        text
      </code>
    </td>
    
    <td>
      <code>
        vector
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Reranker
    </td>
    
    <td>
      <code>
        text-ranking
      </code>
    </td>
    
    <td>
      <code>
        text
      </code>
    </td>
    
    <td>
      <code>
        score
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      語音轉文字
    </td>
    
    <td>
      <code>
        audio-to-text
      </code>
    </td>
    
    <td>
      <code>
        audio
      </code>
    </td>
    
    <td>
      <code>
        text
      </code>
    </td>
  </tr>
</tbody>
</table>

### sources

依優先順序排列的下載來源。每一項需要 `provider`（`huggingface`、`modelscope`、`ollama` 或 `custom`）與 `modelId`。加上 `files` 可將下載範圍縮限到特定檔案，由 llama.cpp 服務的 GGUF 建置一定要這樣寫。

檔名必須與來源方的檔案清單完全一致，請實際查閱而不要憑印象填寫。另請注意，這裡的 `ollama` 是下載來源，不是推論引擎。

## deployment.engines

至少一個引擎，每一項都要有 `name` 與此模型在該引擎上服務的 `apiEndpoints`：

```yaml
deployment:
  type: model
  engines:
    - name: llama.cpp
      version: ">=0.11.0"          # 選用
      apiEndpoints:
        - /v1/chat/completions
      contextWindow: 32768
```

引擎名稱必須能對應到驗證器內建的推論引擎目錄：GGUF 用 `llamacpp`（別名 `llama.cpp`、`llama_cpp`），safetensors 用 `vllm` 與 `nvidia-vllm`，ct2 語音轉文字用 `whisper`（別名 `faster-whisper`）。其他名稱一律驗證失敗。

`contextWindow` 至少要宣告在第一個引擎上——應用程式的依賴條件比對的就是這個值。

## resources

依實際檔案與實測的服務用量估算：`storage` 是實際下載內容的大小，`vram` 是權重加上在所宣告 context window 下的 KV cache，並保留餘裕。純 CPU 模型填 `gpu: 0` 與 `vram: null`。

## 選用檔案

`icon.svg` 是 AI Model Center 列出這個 collection 時使用的圖示——正方形、256×256 以上、透明背景，優先使用 SVG。

`localization.yaml` 負責翻譯使用者可見的字串，模型會在兩個層級各有一份：一份放在 `collection.yaml` 旁，一份放在每個 variant 目錄內。模型名稱不翻譯——型號在任何語言中都是同一個寫法。

## 下一步

<card-group>
<card icon="i-lucide-handshake" title="透過官方通道出貨" to="https://developer.ardge.com/zh-tw/guide/model-provider/shipping-channel">

從自行部署的 template，走向以 ARDGE 合作夥伴身分將模型交付給客戶

</card>
</card-group>


## Sitemap

See the full [sitemap](https://developer.ardge.com/sitemap.md) for all pages.