中国机动车驾驶证识别与抽取

intent

extract structured data from chinese driving licenses (front and back) using laiye's agentic document processing (adp) platform. returns json with 11 key fields: license number, name, gender, nationality, address, date of birth, first issue date, permit type, validity period, issuing agency, and file number. use this for driver verification workflows, rideshare/freight driver screening, and compliance checks. zero setup required beyond api key and cli install.

inputs

external connections:

• laiye adp platform api (regional: china mainland at https://adp.laiye.com/ or global at https://adp-global.laiye.com/)
• adp cli tool (@laiye-adp/agentic-doc-parse-and-extract-cli via npm or shell script)

required parameters:

• api_key: adp account api key (obtain at regional portal after registration, new accounts get 100 free credits monthly, ~200 free license extractions)
• api_base_url: regional api endpoint (mainland: https://adp.laiye.com/ or global: https://adp-global.laiye.com/)
• app_id: driving license extraction app id (format: ootb_* for built-in app, queried via adp app-id list --app-type 0)
• input_source: one of (1) url pointing to license image, (2) local file path, (3) local folder path for batch, or (4) base64 encoded image
• file_name (base64 mode only): filename with extension (e.g., license.jpg)

environment setup:

• ADP_API_KEY: optional env var to store api key (avoids repeated flag passing)
• ADP_API_BASE_URL: optional env var to store region-specific base url

file constraints:

• max single file size: 50mb
• supported formats: jpg, jpeg, png, bmp, tiff, tif, pdf, doc, docx, xls, xlsx
• concurrency limits: free tier 2 parallel docs, paid tier 10 parallel docs

procedure

1. install adp cli (first run only)

   • input: system with npm or shell/powershell access
   • run npm install -g @laiye-adp/agentic-doc-parse-and-extract-cli (npm, all platforms) or shell/powershell script from github
   • output: adp command available in terminal

2. configure api credentials (first run only)

   • input: api key from regional adp portal, regional api base url
   • run adp config set --api-key <your-api-key> and adp config set --api-base-url <regional-url>
   • optional: store in env vars ADP_API_KEY and ADP_API_BASE_URL
   • output: config file written to local system config directory

3. verify credentials (first run only)

   • input: configured api key and base url
   • run adp config get
   • output: displays current api key, base url, and auth status
   • if config missing, halt and prompt user to complete step 2

4. query and cache app id (first run only, or on app list refresh)

   • input: none (uses existing auth config)
   • run adp app-id list --app-type 0 to fetch built-in apps
   • scan returned json array for object with app_label containing "驾驶证" (driving license)
   • extract and store app_id value (format: ootb_*)
   • output: app id cached locally (e.g., in memory or config file for reuse)
   • fallback: if no OOTB app found, run adp app-id list without filter and manually locate license app

5. prepare input source

   • input: license image as url, local file path, local folder path, or base64 string
   • validate: url is reachable, file exists and under 50mb, folder contains valid formats
   • output: input source ready for extract command

6. execute extraction (single or batch)

   • input: app id, input source, optional export path
   • for single url: run adp extract url <url> --app-id <app_id>
   • for single local file: run adp extract local <file_path> --app-id <app_id>
   • for base64: run adp extract base64 <base64_string> --app-id <app_id> --file-name <name.ext>
   • for batch folder: run adp extract local <folder_path> --app-id <app_id> --export <output_dir>
   • output: json response (single) or summary json + per-file output jsons (batch)

7. parse and validate response

   • input: json response from step 6
   • extract array of field objects, each with field_key, field_name, field_values (array of objects with field_value string)
   • validate: response contains all 11 expected field keys (driver_license_number, name, gender, nationality, date_of_birth, first_license_issue_date, driving_permit_type, validity_period_start_end, issuing_agency, residential_address, file_number)
   • output: parsed fields dict or validated json structure

8. apply pii masking (mandatory before output/storage)

   • input: extracted field values, especially driver_license_number, name, residential_address, date_of_birth, file_number
   • mask: keep first 6 and last 4 chars of license number, mask middle; keep surname only for name; truncate address to city level; mask full date of birth
   • output: masked json ready for storage or downstream systems
   • note: do not output raw pii to logs, console, ui, or external systems

9. store or forward results

   • input: masked json from step 8
   • write to database, file system, api endpoint, or return to caller
   • output: confirmation of successful storage (record id, file path, api status code, etc.)

decision points

if credentials not configured

• run adp config get to check
• if missing, prompt user to visit regional adp portal (https://adp.laiye.com/ or https://adp-global.laiye.com/), register/login, copy api key, and run step 2
• do not proceed without valid auth

if app id not cached

• run adp app-id list --app-type 0 and scan for "驾驶证"
• if found, cache the app_id for future runs to avoid repeated queries
• if not found in OOTB apps, run adp app-id list without filter and manually search
• if still not found, halt with error: "no driving license extraction app found in account"

if input source is url

• check url is reachable (http get with timeout)
• if 404 or timeout, halt with error before calling adp
• else proceed with adp extract url

if input source is local file

• check file exists and is under 50mb
• if not, halt with error
• else check format is in (jpg, jpeg, png, bmp, tiff, tif, pdf, doc, docx, xls, xlsx)
• if not, halt with unsupported format error
• else proceed with adp extract local

if input source is local folder (batch)

• check folder exists and is not empty
• count files and warn if > 100 (high-volume batch)
• proceed with adp extract local <folder> and export option
• after batch, check returned summary: if failed > 0, log failed file list with errors

if input source is base64

• decode to validate string is valid base64
• if decode fails, halt with error
• require --file-name parameter with valid extension
• else proceed with adp extract base64

if response status is success (exit code 0)

• parse json, validate 11 expected fields present
• if field_values empty for a field (e.g., file_number), log warning but continue
• apply pii masking and return result

if response status is partial failure (exit code 6, batch mode)

• parse summary json: total, success, failed, files array
• log success count and failed file details with error reasons
• return success list to caller, optionally retry failed files

if response status is auth error (exit code 4)

• check if api key expired (contact laiye support or regenerate in portal)
• check if api base url is correct region
• do not retry immediately; prompt user to verify credentials
• halt with actionable error message

if response status is rate limit exceeded

• check concurrency: free tier max 2, paid tier max 10 parallel docs
• if batch exceeds limit, queue and retry with backoff
• else halt with error: "rate limit exceeded, try again in 60 seconds"

if response status is insufficient credits

• run adp credit to check remaining balance
• halt with error: "insufficient credits (cost 0.5 per license), please recharge at portal"

if response status is parameter error (exit code 2)

• check app_id format (should be ootb_* or custom string)
• check file path and url syntax
• check for typos in command flags
• halt with error message pointing to invalid parameter

if file exceeds 50mb or unsupported format

• reject before calling adp api to avoid wasting credits
• halt with clear error

if pii masking fails or is skipped

• log critical warning: "pii masking not applied, raw sensitive data exposed"
• do not store or forward raw pii
• halt until masking is confirmed

if network timeout or adp service unavailable

• retry up to 3 times with exponential backoff (1s, 2s, 4s)
• if all retries fail, halt with error: "adp service unavailable, try again later"

output contract

success case (single file):

• format: json array of 11 field objects
• structure: [{ "field_key": string, "field_name": string, "field_values": [{ "field_value": string }] }, ...]
• location: return to caller or write to specified file path
• masking: all pii fields (driver_license_number, name, residential_address, date_of_birth) must be masked before output
• example:

[
  {
    "field_key": "driver_license_number",
    "field_name": "驾驶证证号",
    "field_values": [{"field_value": "150402****3122"}]
  },
  {
    "field_key": "name",
    "field_name": "姓名",
    "field_values": [{"field_value": "谢*"}]
  },
  {
    "field_key": "gender",
    "field_name": "性别",
    "field_values": [{"field_value": "女"}]
  },
  {
    "field_key": "nationality",
    "field_name": "国籍",
    "field_values": [{"field_value": "中国"}]
  },
  {
    "field_key": "date_of_birth",
    "field_name": "出生日期",
    "field_values": [{"field_value": "****-02-22"}]
  },
  {
    "field_key": "first_license_issue_date",
    "field_name": "初次领证日期",
    "field_values": [{"field_value": "2015-06-18"}]
  },
  {
    "field_key": "driving_permit_type",
    "field_name": "准驾车型",
    "field_values": [{"field_value": "C1"}]
  },
  {
    "field_key": "validity_period_start_end",
    "field_name": "有效期始至",
    "field_values": [{"field_value": "2015-06-18 至 2021-06-18"}]
  },
  {
    "field_key": "issuing_agency",
    "field_name": "签发机构",
    "field_values": [{"field_value": "河北省秦皇岛市公安局交通警察支队"}]
  },
  {
    "field_key": "residential_address",
    "field_name": "住址",
    "field_values": [{"field_value": "内蒙古自治区赤峰市"}]
  },
  {
    "field_key": "file_number",
    "field_name": "档案编号",
    "field_values": []
  }
]

success case (batch):

• format: summary json + per-file output json files
• summary structure: { "total": int, "success": int, "failed": int, "output_dir": string, "files": [{ "input": string, "output": string, "status": "success"|"failed", "error": string (optional) }] }
• location: output_dir contains one json per input file (name.jpg.json for success, name.jpg.error.json for failures)
• masking: applied to all output jsons
• example summary:

{
  "total": 10,
  "success": 9,
  "failed": 1,
  "output_dir": "/absolute/path/to/results",
  "files": [
    {"input": "license-001.jpg", "output": "license-001.jpg.json", "status": "success"},
    {"input": "damaged.jpg", "output": "damaged.jpg.error.json", "status": "failed", "error": "image too blurry"}
  ]
}

async success case:

• format: task_id string
• location: return to caller, user polls with adp extract query <task_id>
• polling: call query command periodically until status = "completed" or "failed"
• result: upon completion, download or retrieve final json

error case:

• format: json error object or plain text error message
• structure: { "type": string, "message": string, "fix": string (optional), "retryable": boolean, "details": object (optional) }
• location: stderr or error log
• exit code: non-zero (1-6 depending on error type)
• example:

{
  "type": "AUTH_ERROR",
  "message": "Authentication error: invalid API key",
  "fix": "Check your API key is correct and has not expired.",
  "retryable": false,
  "details": {"context": "extract"}
}

cost tracking:

• each license extraction costs 0.5 credits
• batch of 10 licenses costs 5 credits
• new accounts: 100 free credits/month (200 free extractions/month), resets monthly
• run adp credit to check balance, recharge at regional portal if needed

outcome signal

user sees success when:

• command exits with code 0
• json response is returned with all 11 expected field keys
• at least the main fields (license number, name, permit type) have non-empty field_values arrays
• masked output is logged or stored without raw pii visible
• no warnings or errors in stderr

user sees failure when:

• command exits with non-zero code (1-6)
• error json or error message appears in stderr with actionable fix
• json response is missing expected fields or malformed
• raw pii appears in output (masking failed)
• network timeout or adp service error is reported

progress signal (batch/async):

• for batch: summary json shows total vs success count
• for async: task_id returned immediately, polling status changes from "pending" to "completed" or "failed"
• each completed file in batch shows "success" or "failed" status

credit deduction signal:

• user can run adp credit before and after extraction to see credit cost (0.5 per license)
• if insufficient credits, extraction halts with clear error message and recharge link

---

credits: original design and cli tool by laiye technology (beijing) co., ltd. adp platform: https://adp.laiye.com/ (mainland china) or https://adp-global.laiye.com/ (global). support: global_product@laiye.com, github issues at https://github.com/laiye-ai/adp-cli/issues.