> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/tech/quickstart/parser.md).

# Parser 解析工具

知識庫的文件解析器與語音轉文字解析器：各解析器支援的格式、處理圖片與掃描檔的方式、能否離線運作、自動偵測的選擇規則與計費方式。

## 什麼是 Parser？ <a href="#what-is-parser" id="what-is-parser"></a>

Parser（解析器）把上傳到知識庫的原始檔案轉成文字，是向量化與檢索的前一步。解析品質直接決定後面找不找得到內容：表格是否保留結構、圖片與掃描頁的文字是否被讀出來，都在這一步決定。

<figure><img src="https://527168072-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F38pkhhqHl1oA6yyE9R2n%2Fuploads%2Fgit-blob-0ce05108866ecded0daa5a9fb3cd8b9137ffef26%2F2%20(1).png?alt=media" alt=""><figcaption><p>RAG 流程</p></figcaption></figure>

上傳時可以為每個檔案指定解析器，後台操作見使用者手冊的 [如何建立知識庫：基本設置](https://docs.maiagent.ai/build/knowledge-base/km-basic-settings)。各解析器可用的檔案類型，也可以呼叫 `GET /api/v1/allowed-file-specs/` 取得。

***

## 文件解析器 <a href="#document-parsers" id="document-parsers"></a>

MaiAgent 雲端目前提供三種文件解析器：

| 項目        | MaiAgent Parser（預設）                                                                                                                                                            | MaiAgent Parser (Offline)                   | Vision Parser                                      |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------- | -------------------------------------------------- |
| 處理方式      | 直接讀取檔案內的文字、表格與圖片                                                                                                                                                               | 以版面分析保留文件結構（標題、表格）                          | 由雲端多模態模型逐頁「看」文件並轉成 Markdown                        |
| 圖片與掃描頁    | 擷取內嵌圖片；沒有文字層的向量繪圖頁會做 OCR                                                                                                                                                       | 設定多模態模型後，PDF 會加做 OCR 與圖片描述                  | 以視覺理解讀出圖片、圖表與掃描頁的內容                                |
| 使用大型語言模型  | 否                                                                                                                                                                              | 只有設定多模態模型時                                  | 是                                                  |
| 離線（無網路）環境 | 可以                                                                                                                                                                             | 可以；圖片描述需在地端部署多模態模型                          | 不行，需連線到雲端模型                                        |
| 支援格式      | `.pdf` `.doc` `.docx` `.odt` `.xls` `.xlsx` `.csv` `.ods` `.ppt` `.pptx` `.odp` `.epub` `.txt` `.json` `.jsonl` `.md` `.eml` 與圖片檔 `.png` `.jpg` `.jpeg` `.gif` `.webp` `.tiff` | `.pdf` `.docx` `.pptx` `.md` `.html` `.htm` | `.pdf` `.doc` `.docx` `.odt` `.ppt` `.pptx` `.odp` |

* **圖片檔**（`.png`、`.jpg` 等）要放進知識庫，知識庫必須使用支援多模態的 Embedding 模型，見 [Embedding 模型](https://docs.maiagent.ai/tech/quickstart/embedding.md#before-you-choose)。
* MaiAgent Parser (Online) 目前由平台統一停用，無法選用。
* 地端部署可用的解析器依部署設定而定，請洽 MaiAgent 窗口。

#### 「自動偵測（預設）」與解析計費 <a href="#auto-detect-and-billing" id="auto-detect-and-billing"></a>

上傳 PDF、Word（.docx）、PowerPoint（.pptx）到知識庫時，上傳視窗每個檔案旁的解析器下拉選單預設是 <mark style="color:blue;">自動偵測（預設）</mark>，不是固定使用 MaiAgent Parser。系統會在上傳後讀取檔案結構再決定解析器：

* 只有文字、沒有明顯圖片內容的檔案 → 使用該檔案類型的預設解析器（一般為 MaiAgent Parser）
* 掃描檔（沒有文字層）、含圖片內容的檔案（例如工程圖面、掃描件）與 PowerPoint → 系統從支援 OCR 或視覺理解的解析器（MaiAgent Parser (Offline)、Vision Parser）中挑選；找不到合適的解析器時使用預設解析器

判斷依據是檔案結構（有沒有文字層、含圖片與含表格的頁數），不是圖片張數多寡；Word 檔只要內嵌圖片就視為含圖片內容。因此只有少量圖片的文件仍可能改用上述解析器，實際結果以知識庫文件列表 <mark style="color:blue;">解析器</mark> 欄顯示的解析器為準。

點數依**實際完成解析的那個解析器**計算。各解析器的計費單位、重新解析與換解析器的扣點規則，見使用者手冊 [用量計算：各解析器的計費單位](https://docs.maiagent.ai/others/usage#parser-billing-units)。對帳時，每筆解析費用在組織 Credits 的 <mark style="color:blue;">消耗記錄</mark> 中以下列描述記錄（匯出 CSV 的「描述」欄；也可以用 <mark style="color:blue;">搜尋</mark> 輸入檔名查詢）：

| 解析器                       | 消耗記錄的描述                                                |
| ------------------------- | ------------------------------------------------------ |
| MaiAgent Parser           | `Document parsing (maiagent): 檔名`                      |
| MaiAgent Parser (Offline) | `Document parsing (docling): 檔名`                       |
| Vision Parser             | `Vision parsing input: 檔名`、`Vision parsing output: 檔名` |

{% hint style="warning" %}
在文件列表更換解析器（含 <mark style="color:blue;">批量修改解析器</mark>）會立即重新解析，沒有確認視窗。要固定解析成本、避免自動改用其他解析器，請在上傳時直接選擇 MaiAgent Parser（或其他指定的解析器），不要使用 <mark style="color:blue;">自動偵測（預設）</mark>。
{% endhint %}

#### 圖片過大導致解析失敗 <a href="#oversized-images" id="oversized-images"></a>

文件內嵌的圖片有尺寸上限，超過時依解析器有兩種結果：

* **Vision Parser** 會略過單邊超過 8,000 px 或像素總數（寬 × 高）超過 4,000 萬的內嵌圖片，只以整頁影像辨識，不會讓整份文件失敗；被略過的圖片內容若是重點，請先把圖片縮小再重新上傳。
* **其他解析器**在解碼超大圖片時可能整份失敗，文件列表的 <mark style="color:blue;">失敗原因</mark> 會出現 `total decoded image size must be at most … pixels` 這類訊息，代表文件中有圖片的像素總數超過該解析器的解碼上限。處理方式：把來源文件中的圖片縮小或壓縮後重新上傳；掃描檔改用 Vision Parser；只需要文字時，先把文件另存為不含圖片的版本。

{% hint style="info" %}
上限以像素總數計，不是檔案大小：一張 8,000 × 8,000 的截圖（6,400 萬像素）即使壓成很小的 JPEG 也會超過。縮圖時把長邊控制在 4,000 px 以內最保險。
{% endhint %}

***

## 語音轉文字解析器 <a href="#speech-parsers" id="speech-parsers"></a>

音訊檔上傳到知識庫後，由語音轉文字解析器轉成逐字稿再建立索引。MaiAgent 雲端目前提供：

| 解析器（後台名稱）       | 服務                     | 語言設定                  | 自訂提示詞 | 可上傳影片檔 |
| --------------- | ---------------------- | --------------------- | ----- | ------ |
| Azure Speech    | Azure 語音服務             | 可指定，最多 4 種            | 否     | 否      |
| WhisperGroq     | Groq（Whisper large-v3） | 可指定 1 種，或自動偵測         | 是     | 是      |
| WhisperOpenAI   | OpenAI（Whisper）        | 可指定 1 種，或自動偵測         | 是     | 是      |
| Bronci (長問語音辨識) | Bronci                 | 台語、台灣華語、客語（四縣、海陸），擇 1 | 否     | 否      |

語音轉文字依音訊秒數計費，每次重新轉錄都會再計費，見使用者手冊 [用量計算：各解析器的計費單位](https://docs.maiagent.ai/others/usage#parser-billing-units)。消耗記錄的描述為 `Audio parsing (服務代碼): 檔名`，例如 `Audio parsing (azure): 檔名`。

地端部署的語音轉文字由部署包設定：新部署預設使用本機的 LocalAI 服務（模型為 Qwen3-ASR 或 Whisper，需要 GPU），既有站台可沿用 Whisper (Offline)。兩者都在地端執行，音訊不會送到雲端。

音訊檔解析完成後，可以在知識庫檢視逐字稿，並下載 TXT（純文字）或 SRT（字幕格式）：


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.maiagent.ai/tech/quickstart/parser.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
