Parser 解析工具

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

什麼是 Parser？

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

RAG 流程

上傳時可以為每個檔案指定解析器，後台操作見使用者手冊的 如何建立知識庫：基本設置。各解析器可用的檔案類型，也可以呼叫 GET /api/v1/allowed-file-specs/ 取得。

---

文件解析器

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 模型。

• MaiAgent Parser (Online) 目前由平台統一停用，無法選用。

• 地端部署可用的解析器依部署設定而定，請洽 MaiAgent 窗口。

Gemini 影像辨識解析器

除了上表三種，平台另可開通以 Gemini 3.1 Pro Preview（經 Google Vertex AI）進行影像辨識（OCR）的解析器，適用格式與 Vision Parser 相同（.pdf 與 Word、PowerPoint、OpenDocument 文件，Office 檔會先轉成 PDF）。

項目	說明
處理方式	整份 PDF 一次送給模型辨識，不逐頁拆開
單檔上限	50 MB 或 1,000 頁
整份辨識失敗時	自動改為每 50 頁一批重送
計費	依模型實際的輸入與輸出用量計入 Credits，在消耗記錄中同樣以 Vision parsing input: 檔名、Vision parsing output: 檔名 記錄
離線（無網路）環境	不行，需連線到 Vertex AI

預設解析器與「自動偵測（預設）」的挑選規則不受影響，需要時在上傳視窗或文件列表的 解析器 下拉選單手動選用。解析器清單由平台設定，清單中沒有這個選項時請洽 MaiAgent 窗口。

「自動偵測（預設）」與解析計費

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

• 只有文字、沒有明顯圖片內容的檔案 → 使用該檔案類型的預設解析器（一般為 MaiAgent Parser）

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

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

點數依實際完成解析的那個解析器計算。各解析器的計費單位、重新解析與換解析器的扣點規則，見使用者手冊 用量計算：各解析器的計費單位。對帳時，每筆解析費用在組織 Credits 的 消耗記錄 中以下列描述記錄（匯出 CSV 的「描述」欄；也可以用 搜尋 輸入檔名查詢）：

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

在文件列表更換解析器（含 批量修改解析器）會立即重新解析，沒有確認視窗。要固定解析成本、避免自動改用其他解析器，請在上傳時直接選擇 MaiAgent Parser（或其他指定的解析器），不要使用 自動偵測（預設）。

圖片過大導致解析失敗

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

• Vision Parser 會略過單邊超過 8,000 px 或像素總數（寬 × 高）超過 4,000 萬的內嵌圖片，只以整頁影像辨識，不會讓整份文件失敗；被略過的圖片內容若是重點，請先把圖片縮小再重新上傳。

• 其他解析器在解碼超大圖片時可能整份失敗，文件列表的 失敗原因 會出現 total decoded image size must be at most … pixels 這類訊息，代表文件中有圖片的像素總數超過該解析器的解碼上限。處理方式：把來源文件中的圖片縮小或壓縮後重新上傳；掃描檔改用 Vision Parser；只需要文字時，先把文件另存為不含圖片的版本。

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

---

語音轉文字解析器

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

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

語音轉文字依音訊秒數計費，每次重新轉錄都會再計費，見使用者手冊 用量計算：各解析器的計費單位。消耗記錄的描述為 Audio parsing (服務代碼): 檔名，例如 Audio parsing (azure): 檔名。

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

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