證件辨識

使用多模態 AI 辨識身分證等證件圖片，自動輸出結構化 JSON 資料

企業在處理身分驗證、開戶、報到等流程時，經常需要人工逐一輸入證件上的姓名、身分證字號、地址等資訊，不僅耗時且容易出錯。透過 MaiAgent 的多模態 AI 助理，使用者只需上傳證件照片，系統即可自動辨識並輸出結構化 JSON 資料，可直接串接至後續業務系統。

與傳統 OCR 方案相比，MaiAgent 結合大型語言模型的多模態能力，具備以下優勢：

	傳統 OCR 引擎	MaiAgent 多模態 AI
版面適應性	需針對每種證件設計模板	自動理解不同證件版面
正反面處理	需分開處理並手動對應	單張圖片即可同時辨識正反面
欄位擴充	需修改程式碼	修改 JSON Schema 即可
部署成本	自建 OCR 服務或購買授權	平台設定，無需撰寫程式碼
錯誤處理	回傳原始文字，需後處理	AI 理解語意，自動修正格式

應用場景

• 金融業開戶：客戶上傳身分證，自動擷取姓名、證號等資訊填入開戶表單

• 人資報到流程：新進員工上傳證件，系統自動建檔

• 醫療掛號：患者上傳健保卡或身分證，自動填入基本資料

• 政府機關臨櫃：民眾出示證件，即時辨識並帶入申辦表單

解決方案架構

建置步驟

Step 1：建立 AI 助理

1. 左側選單 → AI 功能 → AI 助理

2. 點擊右上角 建立 AI 助理

3. 填寫基本設定：

欄位	填寫內容
助理名稱	證件 OCR 辨識助理
大語言模型	Gemini 3.1 Flash-Lite（需支援多模態）

建立 AI 助理基本設定

選擇大語言模型時，請確認該模型支援多模態（圖片輸入），例如 Gemini 系列。若選用純文字模型，將無法辨識圖片內容。

Step 2：設定回覆模式與 JSON Schema

切換至 回答模式設定 頁籤：

欄位	填寫內容
回答模式	RAG 問答
輸出格式	輸出 JSON 格式

選擇 輸出 JSON 格式 後，在下方的 JSON Schema 欄位中填入以下內容：

{
  "type": "object",
  "properties": {
    "document_type": {
      "type": "string",
      "description": "證件類型，如中華民國國民身分證、駕照、護照、健保卡、居留證等"
    },
    "name": {
      "type": "string",
      "description": "持證人完整姓名，從正面姓名欄位讀取"
    },
    "gender": {
      "type": "string",
      "enum": ["男", "女"],
      "description": "性別"
    },
    "date_of_birth": {
      "type": "string",
      "description": "出生年月日，民國年格式"
    },
    "military_service": {
      "type": ["string", "null"],
      "description": "役別，如免役、已服、未服、替代役。女性或無此欄位則為 null"
    },
    "place_of_birth": {
      "type": ["string", "null"],
      "description": "出生地，從背面讀取"
    },
    "id_number": {
      "type": "string",
      "description": "身分證統一編號，1 英文字母 + 9 數字"
    },
    "expiry_or_issue_date": {
      "type": ["string", "null"],
      "description": "截切日期（發證日期或有效期限），民國年格式"
    },
    "address": {
      "type": ["string", "null"],
      "description": "完整住址，從背面住址欄位讀取，包含縣市區里鄰路段巷弄號樓"
    }
  },
  "required": [
    "document_type", "name", "gender", "date_of_birth",
    "military_service", "place_of_birth", "id_number",
    "expiry_or_issue_date", "address"
  ]
}

JSON Schema 輸出格式設定

Step 3：撰寫角色指令

在同一頁籤的 角色指令 區塊中，填入以下內容：

你是一個專業的證件 OCR 辨識助理。使用者會上傳證件圖片，你必須仔細辨識圖片中的所有文字並擷取關鍵資訊。

## 最重要：仔細掃描整張圖片的所有區域

⚠️ 使用者經常在同一張圖片中同時拍攝證件的正面和背面（左右並排或上下排列）。你必須：
1. 先掃描整張圖片，辨識圖中有幾個證件面（可能是 1 面或 2 面）
2. 分別辨識每個區域的文字
3. 將正面和背面的資訊合併填入結果

絕對不可以說「背面未提供」或「資訊不在圖片中」，除非你確實在整張圖片的所有區域都找不到該資訊。

## 中華民國國民身分證欄位位置

### 正面（有國旗、照片）
- 「姓名」：照片旁邊，這是持證人本人的名字
- 「出生年月日」：民國 XX 年 XX 月 XX 日
- 「性別」：標示「男」或「女」
- 「統一編號」：底部，1 個英文大寫字母 + 9 個數字
- 「發證日期」：底部左側

### 背面（有父母配偶欄位，背景通常較暗）
- 「父」「母」：父母姓名（不是持證人）
- 「配偶」：配偶姓名
- 「役別」：兵役狀態
- 「出生地」：如「臺北市」「新北市」
- 「住址」：完整戶籍地址

## 辨識規則
1. 證件類型：根據外觀判斷
2. 名字：必須從正面的「姓名」欄位讀取，不可讀成背面的父/母/配偶
3. 性別：從正面讀取
4. 出生年月日：從正面讀取，民國年格式
5. 役別：從背面讀取。女性通常無役別填 null
6. 出生地：從背面讀取
7. 身分證字號：從正面底部讀取，逐字仔細辨識
8. 截切：從正面的「發證日期」欄位讀取
9. 住址：從背面的「住址」欄位讀取，完整包含縣市區里鄰路段巷弄號樓

## 輸出注意事項
- 無法辨識的欄位填入 null
- 所有辨識結果必須忠實於圖片內容，不可推測或編造

角色指令設定

點擊 儲存 完成助理建立。

Step 4：測試辨識效果

1. 進入助理的 測試對話

2. 上傳一張證件圖片（可同時包含正反面）

3. 輸入「請辨識這張證件圖片」

4. 確認回傳的 JSON 結構與欄位內容正確

證件辨識測試結果

使用範例

上傳一張包含身分證正反面的圖片，AI 助理會自動辨識並輸出結構化 JSON：

{
  "document_type": "中華民國國民身分證",
  "name": "陳筱玲",
  "gender": "女",
  "date_of_birth": "民國57年6月5日",
  "military_service": null,
  "place_of_birth": "臺北市",
  "id_number": "A234567890",
  "expiry_or_issue_date": "民國94年7月1日",
  "address": "臺北市內湖區葫洲里1鄰民權東路六段283巷165弄218號"
}

辨識準確度取決於圖片品質。建議拍攝時確保光線充足、避免反光，並將證件平放拍攝。若同時拍攝正反面，建議左右並排或上下排列。

JSON 輸出欄位說明

欄位	型別	來源	說明
document_type	string	正面	證件類型
name	string	正面	持證人姓名
gender	string	正面	性別（男/女）
date_of_birth	string	正面	出生年月日（民國年）
military_service	string/null	背面	役別
place_of_birth	string/null	背面	出生地
id_number	string	正面	身分證統一編號
expiry_or_issue_date	string/null	正面	發證日期
address	string/null	背面	完整住址

API 串接

此助理可透過 MaiAgent API 串接至業務系統，實現自動化證件辨識流程。

呼叫流程

Step 1：上傳圖片取得附件 ID

curl -X POST \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -F "file=@/path/to/id_card.jpeg" \
  "https://api.maiagent.ai/api/v1/attachments-upload/"

回傳結果中記下 id、type、file、filename 欄位，下一步會用到。

Step 2：呼叫助理進行辨識

curl -X POST \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "content": "請辨識這張證件圖片",
      "attachments": [{
        "id": "{Step 1 回傳的 id}",
        "type": "image",
        "file": "{Step 1 回傳的 file URL}",
        "filename": "id_card.jpeg"
      }]
    },
    "isStreaming": false
  }' \
  "https://api.maiagent.ai/api/v1/chatbots/{助理ID}/completions/"

Step 3：解析回傳結果

回傳的 content 欄位即為 JSON 格式的辨識結果：

Python

import json
ocr_result = json.loads(response["content"])
print(ocr_result["name"])             # 陳筱玲
print(ocr_result["id_number"])        # A234567890
print(ocr_result["address"])          # 臺北市內湖區葫洲里1鄰民權東路六段283巷165弄218號

JavaScript

const ocrResult = JSON.parse(response.content);
console.log(ocrResult.name);             // 陳筱玲
console.log(ocrResult.id_number);        // A234567890
console.log(ocrResult.address);          // 臺北市內湖區葫洲里1鄰民權東路六段283巷165弄218號

完整範例程式碼請參考 Playma-Co-Ltd/maiagent-api-examples。