> 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 解析工具

### 什麼是 RAG Parser？

RAG Parser 是 Retrieval-Augmented Generation (RAG) 系統中的關鍵步驟，負責解析與拆解原始資料，作為 Embedding 向量化處理的前置步驟，為後續的向量化與語意檢索提供基礎，對整體資料品質與檢索效果有決定性影響。

<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>

***

### 一、文件解析類 Parser

MaiAgent 提供四種文件解析器，適用於 PDF、Word、Excel、圖片等多種文檔格式：

| 功能特性     | MaiAgent Parser（預設） | MaiAgent Parser（Online） | MaiAgent Parser（Offline）     | Vision Parser          |
| -------- | ------------------- | ----------------------- | ---------------------------- | ---------------------- |
| 價格成本     | 低                   | 高                       | 中                            | 高                      |
| 圖片內容解析效果 | 無法解析圖片中的文字          | 僅 OCR 可解析圖片中的文字         | OCR + AI 理解圖片語意              | AI 視覺理解，效果最佳           |
| 使用 LLM   | 否                   | 是                       | 是                            | 是                      |
| 文字解析效果   | 標準                  | 好                       | 好（結構保留佳）                     | 好                      |
| 表格解析     | 原生提取                | AI 智慧提取圖片裡面的文字          | 原生結構保留（最佳），除了視覺理解外還包含圖片的靜態資源 | AI 視覺辨識將圖片產生視覺理解後的文字內容 |
| 解析時間     | 快                   | 中                       | 慢                            | 慢                      |
| 落地（無網路）  | 可以                  | 不行                      | 可以，但需部署 VLM                  | 不行                     |
| 支援格式數    | 22 種                | 20 種                    | 20 種（僅 PDF 支援 OCR）           | 7 種                    |

#### 「自動偵測（預設）」與解析計費 <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 (Online)、MaiAgent Parser (Offline)、Vision Parser）中挑選；找不到合適的解析器時使用預設解析器

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

| 解析器                       | 計費方式                     | <mark style="color:blue;">交易記錄</mark> 顯示               |
| ------------------------- | ------------------------ | ------------------------------------------------------ |
| MaiAgent Parser           | 依解析後的段落數（chunks）計費       | `Document parsing (maiagent): 檔名`                      |
| MaiAgent Parser (Online)  | 依實際計費頁數計費，每次解析都計費        | `Document parsing (llama): 檔名`                         |
| MaiAgent Parser (Offline) | 依解析後的段落數（chunks）計費       | `Document parsing (docling): 檔名`                       |
| Vision Parser             | 依該解析器設定模型的輸入／輸出 token 計費 | `Vision parsing input: 檔名`、`Vision parsing output: 檔名` |

{% hint style="warning" %}

* 檔案處理完成才扣款，處理失敗不扣款。
* 同一個檔案，每一種解析器的費用各最多只收一次（所有 Vision Parser 合併算同一種）。在文件列表換成該檔案沒用過的解析器，會重新解析並依新解析器計費；換回先前用過的解析器、用同一個解析器重新解析、或在不同的 Vision Parser 之間切換，都不會再扣點。
* 例外：MaiAgent Parser (Online) 依實際計費頁數收費，每次解析（含換回它或用它重新解析）都會再計費一次；解析服務命中快取、實際未計費時不扣點。
* 先前解析已扣的點數一律不退回，因此同一個檔案的交易記錄可能同時出現多種解析項目。
* 在文件列表更換解析器（含 <mark style="color:blue;">批量修改解析器</mark>）會立即重新解析，沒有確認視窗。要固定解析成本、避免自動改用其他解析器，請在上傳時直接選擇 MaiAgent Parser（或其他指定的解析器），不要使用 <mark style="color:blue;">自動偵測（預設）</mark>。
  {% endhint %}

***

### 二、語音轉文字類 Parser

MaiAgent 提供四種語音轉文字解析器，可將音訊檔案轉錄為文字後納入知識庫：

| 功能特性     | Azure Speech | Whisper（Groq） | Whisper（OpenAI） | Whisper（Offline） |
| -------- | ------------ | ------------- | --------------- | ---------------- |
| 價格成本     | 高            | 低             | 中               | 免費               |
| 轉錄準確度    | 高            | 高（large-v3）   | 高（whisper-1）    | 高（視本地模型）         |
| 使用 LLM   | 否            | 否             | 否               | 否                |
| 解析速度     | 即時           | 最快            | 中               | 視硬體而定            |
| 落地（無網路）  | 不行           | 不行            | 不行              | 可以               |
| 多語言支援    | 是            | 是（自動偵測）       | 是（自動偵測）         | 是（自動偵測）          |
| 自訂提示詞    | 否            | 是             | 是               | 是                |
| VAD 語音偵測 | —            | 是             | 是               | 是                |
| 資料隱私     | 雲端（Azure）    | 雲端（Groq）      | 雲端（OpenAI）      | 完全本地             |

音訊檔案上傳至知識庫後，系統會自動進行語音轉文字解析，並提供逐字稿檢視與下載功能：

<figure><img src="https://527168072-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F38pkhhqHl1oA6yyE9R2n%2Fuploads%2Fgit-blob-4469fbd2dab86116ded00a868c6bf6519a116bbb%2Faudio-parser-transcript.png?alt=media" alt=""><figcaption><p>逐字稿檢視：顯示時間戳與對應文字內容</p></figcaption></figure>

<figure><img src="https://527168072-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F38pkhhqHl1oA6yyE9R2n%2Fuploads%2Fgit-blob-b982b40158acfa3b364c8728a4c293b96d6d2476%2Faudio-parser-download.png?alt=media" alt=""><figcaption><p>下載逐字稿：支援 TXT（純文字）與 SRT（字幕格式）兩種格式</p></figcaption></figure>


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.