> 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/api/preparation/parser-auto-detection.md).

# 解析器自動偵測結果

知識庫檔案的解析器留給系統自動偵測時，檔案回應的 parserAutoDetection 會帶出選到的解析器、原因類別與判斷用的數字；本篇說明各欄位、何時為 null，以及原因類別與數字的對照

上傳檔案到知識庫時不指定 `parser`（解析器留在「自動偵測（預設）」），系統會依檔案內容替這份檔選解析器。[列出知識庫中的檔案](https://docs.maiagent.ai/api/api-reference/zhi-shi-ku-xin-ban.md#knowledge-bases-files-list)與[取得特定檔案詳情](https://docs.maiagent.ai/api/api-reference/zhi-shi-ku-xin-ban.md#knowledge-bases-files-retrieve)的回應中，每份檔案的 `parserAutoDetection` 會帶出這次判斷選了哪個解析器、為什麼，以及判斷時算出的數字。可以用它在自己的系統裡區分「系統自動選的解析器」與「使用者自己選的解析器」，並顯示選擇的原因。

## 欄位說明 <a href="#fields" id="fields"></a>

| 欄位           | 類型     | 說明                                                                                                 |
| ------------ | ------ | -------------------------------------------------------------------------------------------------- |
| `parser`     | object | 自動偵測實際選到、這份檔正在使用的解析器，欄位與檔案回應的 `parser` 相同（`id`、`name`、`provider`、`isTimestampSttProvider`）         |
| `reason`     | string | 原因類別，見[原因類別](#reasons)                                                                             |
| `facts`      | object | 判斷時算出的數字，見[判斷數字](#facts)；沒有數字時為空物件 `{}`                                                            |
| `detectedAt` | string | 判斷時間，Unix 時間戳記的毫秒字串（見[欄位格式](https://docs.maiagent.ai/api/preparation/conventions.md#field-format)） |

`facts` 的數字是判斷當下算出、之後不重算。用同一個解析器重新解析時不會重新判斷，數字與判斷時間維持原本那一次。

### 何時為 null <a href="#when-null" id="when-null"></a>

`parserAutoDetection` 為 `null` 代表這份檔目前用的解析器不是自動偵測選的，或還沒有判斷結果：

* 上傳或重新解析時指定了解析器（使用者自己選的）。
* 用「批量重新解析檔案」把自動偵測選的解析器改成別的解析器。用同一個解析器重新解析則保留原本的結果。
* 用「批量重新解析檔案」改回自動偵測（該檔的項目明確帶 `"parser": null`），新的判斷還在排隊、尚未完成。判斷完成後會換成新的結果。
* 這項功能上線前上傳的檔案（舊檔不回填）。

{% hint style="info" %}
用[批量重新解析檔案](https://docs.maiagent.ai/api/api-reference/zhi-shi-ku-xin-ban.md#knowledge-bases-files-batch-reparse-partial-update)改回自動偵測時，該檔的項目要明確帶 `"parser": null`。項目裡沒有 `parser` 這個鍵時，這份檔不會更換解析器、也不會重新解析，`parserAutoDetection` 維持原樣。上傳時則可以直接省略 `parser`。
{% endhint %}

## 回應範例 <a href="#example" id="example"></a>

PDF 檔掃描頁多，系統選了 Vision 解析器：

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "filename": "合約掃描檔.pdf",
  "parser": {
    "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "name": "Vision Parser",
    "provider": "anthropic",
    "isTimestampSttProvider": false
  },
  "parserAutoDetection": {
    "parser": {
      "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "name": "Vision Parser",
      "provider": "anthropic",
      "isTimestampSttProvider": false
    },
    "reason": "scanned",
    "facts": {
      "analyzedPages": 50,
      "partial": true,
      "nonBlankPages": 48,
      "scannedPages": 40,
      "imagePages": 42
    },
    "detectedAt": "1760860800000"
  }
}
```

使用者上傳時自己選了解析器：

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440001",
  "filename": "產品手冊.docx",
  "parserAutoDetection": null
}
```

範例只列出相關欄位，其他檔案欄位見各端點的回應結構。

## 原因類別 <a href="#reasons" id="reasons"></a>

| `reason`                 | 意思                                             | `facts`                           |
| ------------------------ | ---------------------------------------------- | --------------------------------- |
| `scanned`                | 內容以掃描頁為主（PDF 或 Word），需要以圖片判讀                   | PDF 或 Word 的數字                    |
| `image_pages`            | PDF 有夠多需要以圖片判讀的頁（掃描頁或其他以圖片為主的頁）                | PDF 的數字                           |
| `large_images`           | Word 內文有夠多大圖                                   | Word 的數字                          |
| `unmeasurable_images`    | Word 內文有圖片，但量不到圖片尺寸，以需要圖片判讀處理                  | Word 的數字，可能為空物件                   |
| `presentation`           | 簡報檔（PPTX）                                      | 空物件                               |
| `no_image_content`       | 沒有需要以圖片判讀的頁，也沒有內文大圖                            | PDF 或 Word 的數字；Word 檔完全沒有圖片時為空物件  |
| `below_threshold`        | 有需要以圖片判讀的頁或內文大圖，但未達選用 Vision 解析器的門檻            | PDF 或 Word 的數字                    |
| `no_content`             | PDF 判斷的頁全部是空白頁                                 | PDF 的數字                           |
| `file_type_not_detected` | 這種檔案類型不做內容判斷（例如舊版簡報 PPT），系統以該類型的預設解析器處理        | 空物件                               |
| `detection_failed`       | 判斷過程出錯，系統以該檔案類型的預設解析器處理                        | 空物件                               |
| `vision_unavailable`     | 內容需要以圖片判讀，但沒有可用的 Vision 解析器；`parser` 是實際使用的解析器 | 與內容類別相同（PDF 或 Word 的數字；PPTX 為空物件） |

{% hint style="warning" %}
判斷規則之後可能新增原因類別。請不要只依上表寫死判斷：遇到不認得的 `reason` 時，請顯示通用說明（例如「系統依檔案內容自動選擇了解析器」），不要報錯或略過整筆檔案。
{% endhint %}

## 判斷數字 <a href="#facts" id="facts"></a>

`facts` 的鍵依檔案類型不同。依上表，PPTX、完全沒有圖片的 Word 檔、不做內容判斷的檔案類型與判斷出錯時為空物件 `{}`。

**PDF**

| 鍵               | 類型      | 說明                                       |
| --------------- | ------- | ---------------------------------------- |
| `analyzedPages` | integer | 判斷時看了幾頁                                  |
| `partial`       | boolean | 是否只看了前面幾頁（檔案頁數超過判斷上限，目前為前 50 頁時為 `true`） |
| `nonBlankPages` | integer | 看過的頁中非空白的頁數                              |
| `scannedPages`  | integer | 看過的頁中的掃描頁數                               |
| `imagePages`    | integer | 看過的頁中需要以圖片判讀的頁數（含掃描頁）                    |

**Word（DOCX）**

| 鍵           | 類型      | 說明      |
| ----------- | ------- | ------- |
| `figures`   | integer | 內文大圖的數量 |
| `textChars` | integer | 內文字數    |

Word 檔完全沒有圖片（`no_image_content`）或量不到圖片尺寸（`unmeasurable_images`）時，`facts` 可能為空物件。讀取時請把每個鍵都當成可能不存在。


---

# 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/api/preparation/parser-auto-detection.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.
