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

# パーサー自動検出結果

ナレッジベースのファイルのパーサーをシステムの自動検出に任せると、ファイルのレスポンスの parserAutoDetection に、選択されたパーサー、理由の分類、判定に使用した数値が含まれます。本ページでは各フィールド、null になる条件、理由の分類と数値の対応について説明します

ナレッジベースにファイルをアップロードする際に `parser` を指定しない場合（パーサーを「自動検出（デフォルト）」のままにした場合）、システムがファイルの内容に応じてパーサーを選択します。[ナレッジベース内のファイル一覧の取得](https://docs.maiagent.ai/api/ja/api-reference/zhi-shi-ku-xin-ban.md#knowledge-bases-files-list)と[特定のファイルの詳細取得](https://docs.maiagent.ai/api/ja/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/ja/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/ja/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 | 冒頭の一部のページのみを確認したかどうかを表します（ファイルのページ数が判定上限を超える場合は `true` です。現在の上限は先頭 50 ページです） |
| `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/ja/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.
