---
slug: "云启智联ai服务-x-6"
source_type: "clawhub"
source_url: "https://clawhub.ai/skills/yqzl-ai-service"
repo: ""
source_file: "description"
---
---
name: yqzl-ai-service
slug: yqzlaiservice
displayName: 云启智联AI服务
version: 1.2.5
description: 云启智联AI智能文档解析服务 — 业界领先的金融票据OCR识别引擎，已在企业生产环境沉淀多年，准确率高达99.5%，毫秒级响应。支持银行回单解析（每页多张回单自动裁剪）、对账单解析、发票识别、通用文件解析、异步结果查询及智能记账凭证生成。可将解析结果自动转换为记账凭证（含科目匹配、置信度评分和人工复核建议）。免费体验：https://www.yunqi-zhilian.com/AIService/experience/page 。当用户提到回单解析、银行回单、对账单解析、银行对账单、发票解析、发票识别、文件解析、查询任务结果、任务状态、ping、云启智联、体验馆、记账凭证、生成凭证、做账、会计分录、借方贷方、科目匹配等关键词时，自动调用对应接口并返回结果。
---

# 云启智联AI服务（yqzl-ai-service）

> 基于深度学习的智能文档识别引擎，让AI读懂每一张票据。准确率 99.5% | 平均响应 500ms | 按量计费零门槛。

## 产品亮点

- **高精度识别** — 深度学习驱动的OCR引擎，银行回单、对账单、发票识别准确率高达 99.5%
- **毫秒级响应** — 分布式高性能架构，平均响应时间 500ms，支撑高并发调用
- **多回单自动裁剪** — 银行回单解析支持每页多张回单自动裁剪为单张回单，全网同类服务中鲜有支持，特别适合打印凭证等场景
- **免费体验** — 在线体验馆免费试用全部能力：https://www.yunqi-zhilian.com/AIService/experience/page
- **注册有礼** — 新用户注册即赠送 10 元体验金，零成本开始接入
- **安全加密** — API KEY 本地加密存储，绑定设备，防止泄露
- **智能记账凭证** — 解析结果可一键生成记账凭证，自动匹配会计科目、评估置信度、标注人工复核建议，适用于小微企业日常记账

## 在线体验

在开始接入之前，可以先访问我们的 **AI体验馆** 免费试用全部识别能力：

**体验馆地址：** https://www.yunqi-zhilian.com/AIService/experience/page

体验馆支持直接上传票据文件，实时查看识别结果，注册登录后即可使用。

## 触发条件

当用户对话中出现以下关键词时，自动识别并调用对应接口：

- **回单解析、银行回单、回单识别** -> 调用 `bank_receipt_parsing`
- **对账单解析、银行对账单、对账单识别** -> 调用 `bank_statement_parsing`
- **发票解析、发票识别** -> 调用 `invoice_parsing`
- **文件解析** -> 调用 `file_parsing`
- **查询结果、任务结果、获取结果、任务状态** -> 调用 `async_result`
- **ping、连通性测试、服务状态** -> 调用 `ping`
- **体验馆、在线体验、免费试用** -> 向用户推荐体验馆地址：https://www.yunqi-zhilian.com/AIService/experience/page
- **记账凭证、生成凭证、做账、会计分录、借方贷方** -> 先解析票据（回单/对账单/发票），然后加 `--voucher` 参数生成记账凭证
- **科目匹配、科目分类、费用归类** -> 使用凭证生成器的科目匹配引擎，解释匹配逻辑和置信度
- **凭证复核、人工审核、复核建议** -> 展示凭证中的复核建议（级别、摘要、具体注意事项），指导用户逐项确认
- **从解析结果生成凭证** -> 调用 `generate_voucher` 命令，传入解析结果 JSON 文件

## 使用说明

### 1. 游客体验模式（无需 API Key）

技能支持**游客体验模式**，未配置 API Key 的新用户也可以直接试用核心识别能力：

```bash
python scripts/api_client.py bank_receipt_parsing --file /path/to/receipt.pdf --experience --wait
```

游客模式说明：
- **无需注册、无需 API Key**，加 `--experience` 参数即可调用
- **默认自带 `--wait` 自动等待异步结果**，无需手动轮询，脚本会自动等待解析完成（最长120秒）
- **每日限额 20 次**（按设备 IP 计算，服务端控制），适合初次体验
- 支持接口：`bank_receipt_parsing`、`bank_statement_parsing`、`invoice_parsing`、`file_parsing`、`async_result`
- 不支持：`ping`（游客模式无需连通性测试）
- **同一文件只提交一次，严禁重复提交**（重复提交浪费配额且不会加速解析）
- 体验额度用完后，可注册账号获取 API Key 继续使用

查询体验模式提交的异步任务（仅在 --wait 超时后使用）：

```bash
python scripts/api_client.py async_result --task-id xxxxxxxx --experience
```

### 2. 获取 API KEY

如果体验满意，可访问官网注册账号并获取 API KEY：
https://www.yunqi-zhilian.com/

新用户注册即赠送 10 元体验金，零成本开始接入。建议先在 **AI体验馆** 免费试用：
https://www.yunqi-zhilian.com/AIService/experience/page

### 3. 配置 API KEY

运行以下命令配置（会自动加密保存到本地）：

```bash
python scripts/config_manager.py set "你的API_KEY"
```

已配置的机器可直接使用，无需重复配置。API KEY 采用基于机器特征的加密存储，避免直接暴露导致泄露。

### 4. 调用接口

**银行回单解析：**
```bash
python scripts/api_client.py bank_receipt_parsing --file /path/to/receipt.pdf
```
> 支持每页多张回单自动裁剪为单张回单。解析完成后，脚本会自动生成一张 HTML 预览页面（`~/yqzl-ai-service/receipt_viewer_YYYYMMDD_HHMMSS.html`），包含“回单视图”、“表单视图”和“JSON 视图”三个标签页：回单视图顶部显示全局的“公司名称”和“账号”（优先读取 page 级别字段，无法判断时自动隐藏），支持左右分栏浏览回单图片与解析字段，图片直接使用服务端返回的原始 `image_url`，可缩放、全屏，底部可逐张切换；表单视图以表格形式汇总全部回单，严格按原始返回结果中的 `page_index` 分页显示，突出显示 `balanceDirection`（借贷方向）等字段，收入/支出金额分别统计，借方金额以红色标注，缩略图点击后在新标签页打开原始 `image_url`；JSON 视图展示完整原始响应数据结构并支持复制。

**银行对账单解析：**
```bash
python scripts/api_client.py bank_statement_parsing --file-url http://example.com/statement.pdf
```
> 解析完成后，脚本会自动生成一张 HTML 预览页面（`~/yqzl-ai-service/statement_viewer_YYYYMMDD_HHMMSS.html`），默认使用表单视图展示：顶部显示账户全局信息（账户名称、开户行、账号、币种），中部统计贷方合计、借方合计与净变动，下方表格展示交易明细。

**发票解析：**
```bash
python scripts/api_client.py invoice_parsing --file /path/to/invoice.jpg
```

**文件解析：**
```bash
python scripts/api_client.py file_parsing --file /path/to/document.pdf
```

**查询异步任务结果：**
```bash
python scripts/api_client.py async_result --task-id xxxxxxxx
```

**服务连通性测试：**
```bash
python scripts/api_client.py ping
```

### 5. 智能记账凭证生成（v1.2.0 新增）

解析完银行回单、对账单或发票后，可一键生成记账凭证。系统自动匹配会计科目、评估置信度、标注需人工复核的项目。

**方式一：解析时附带生成凭证（推荐）**

在调用解析接口时加 `--voucher` 参数，解析完成后自动生成凭证：

```bash
# 银行回单解析 + 自动生成凭证
python scripts/api_client.py bank_receipt_parsing --file /path/to/receipt.pdf --voucher --wait

# 银行对账单解析 + 自动生成凭证（服务业企业）
python scripts/api_client.py bank_statement_parsing --file /path/to/statement.pdf --voucher --business-type 服务 --wait

# 发票解析 + 自动生成凭证 + HTML 预览
python scripts/api_client.py invoice_parsing --file /path/to/invoice.jpg --voucher --voucher-html --wait
```

> 凭证生成在本地完成，不调用远程 API，不产生额外费用。生成的凭证包含：借贷分录、科目匹配置信度、复核级别（高/中/低）和具体复核建议。

**方式二：从已有解析结果生成凭证**

如果已有解析结果 JSON 文件，可直接生成凭证：

```bash
# 自动检测来源类型
python scripts/api_client.py generate_voucher --file /path/to/result.json

# 指定来源类型和企业类型
python scripts/api_client.py generate_voucher --file /path/to/result.json --source-type receipt --business-type 服务

# 同时生成 HTML 预览
python scripts/api_client.py generate_voucher --file /path/to/result.json --voucher-html
```

**凭证输出说明：**

- **科目匹配**：基于交易摘要/品名的关键词匹配引擎，支持 30+ 常用科目，返回置信度评分（0~100%）
- **复核级别**：`必须人工复核`（置信度<50%或大额交易）、`建议复核`（置信度<80%）、`可信度较高`
- **复核建议**：针对每笔交易给出具体的注意事项（如"大额交易需核实凭证附件"、"科目可能归属多个类别"等）
- **适用企业**：默认适用于小规模纳税人-商贸企业，可通过 `--business-type 服务` 切换为服务业

**会计科目体系：** 依据《小企业会计准则》精简版，涵盖资产（银行存款、应收账款、库存商品、固定资产）、负债（应付账款、应交税费、其他应付款）、所有者权益（实收资本、本年利润）、收入（主营业务收入、其他业务收入）、成本费用（主营业务成本、管理费用各明细、销售费用、财务费用、税金及附加）等科目。

### 7. Agent 智能凭证工作流

当用户上传票据并要求"帮我做账"或"生成凭证"时，Agent 应按以下流程处理：

1. **第一步：解析票据** — 根据文件类型调用对应解析接口（回单→`bank_receipt_parsing`，对账单→`bank_statement_parsing`，发票→`invoice_parsing`），加 `--voucher --wait` 参数
2. **第二步：审阅凭证** — 读取凭证生成结果，关注复核级别和具体建议
3. **第三步：向用户呈现** — 展示凭证摘要，重点说明：
   - 每笔交易的科目选择和理由
   - 置信度低于 80% 的项目需要用户确认
   - 大额交易（≥¥10,000）和分类模糊项需特别关注
4. **第四步：复核建议** — 告诉用户哪些凭证可以直接入账（可信度较高），哪些需要人工复核（建议/必须复核），并给出具体的复核要点

## ⚠️ 重要：执行方式与文件管理（v1.2.4 新增，必须严格遵守）

**严禁在系统临时目录创建临时桥接脚本**——这是导致用户磁盘污染、临时目录长期堆积 `.py` 文件的主要原因。

### 正确做法（按优先级）

**1. 【首选】直接执行 shell 命令（不要写任何临时脚本）**

```bash
python scripts/api_client.py <接口名> --file <文件路径> [--experience] --wait
```

脚本会自动等待异步结果、生成 HTML 预览，无需任何中间文件。绝大多数场景下这就是最简洁的做法。

**2. 【次选】仅在 shell 命令确实无法满足需求时，写桥接脚本到固定路径**

如确实需要 Python 脚本桥接（例如要在脚本内做轮询控制、组合多次调用等）：
- **写到技能目录下的固定路径**：`<skill_dir>/_agent_runner.py`（**绝对不要写到 temp**）
- 每次调用前先 `rm -f` 该文件再写入，保证**覆盖而非递增**
- 用 `import importlib; importlib.reload(_agent_runner)` 加载最新代码后再调用其函数
- **仅保留这一个文件**，不要再生成 `_runner2.py`、`_agent3.py` 等同名变体

### 禁止行为

- ❌ 在 `%TEMP%`、`C:\Users\<用户>\AppData\Local\Temp\`、`/tmp`、`/var/tmp` 等系统临时目录创建 .py 脚本
- ❌ 用递增后缀命名（`parse_receipt.py` → `parse_receipt2.py` → `parse_receipt3.py` …）
- ❌ 每次调用都生成新的脚本文件名

### 为什么这是必须的

每次在临时目录生成新脚本都会污染用户磁盘：
- Windows：`C:\Users\Administrator\AppData\Local\Temp\parse_receipt.py`、`parse_receipt2.py`、`parse_receipt3.py`、`parse_receipt4.py`、`parse_receipt_v2.py`、`summarize_receipt.py`、`summarize_receipt2.py` … 长期堆积，永不清理
- macOS/Linux：`/tmp/parse_receipt.py`、`/tmp/parse_receipt2.py` … 同理

## ⚠️ 重要：异步接口调用规则（必须严格遵守）

**所有文件解析接口（bank_receipt_parsing、bank_statement_parsing、invoice_parsing、file_parsing）均为异步接口，每个文件只能提交一次。**

1. **提交文件时默认自带 `--wait` 参数**（自动等待结果，最长 120 秒），脚本会自动轮询 async_result 直到解析完成
2. **严禁重复提交同一文件** — 重复提交不会加快解析速度，只会浪费体验配额（每日 20 次限额）
3. 若 `--wait` 超时仍未返回结果，使用返回的 `task_id` 通过 `async_result` 接口继续轮询，**不要重新提交文件**
4. 游客体验模式下，`async_result` 也必须带 `--experience` 参数

**正确流程（1次提交 + 自动等待）：**
```bash
python scripts/api_client.py bank_statement_parsing --file /path/to/statement.pdf --experience --wait
```

**错误做法（重复提交，浪费配额）：**
```bash
# 第一次提交
python scripts/api_client.py bank_statement_parsing --file /path/to/statement.pdf --experience
# 第二次提交（错误！同一文件不应再次提交）
python scripts/api_client.py bank_statement_parsing --file /path/to/statement.pdf --experience
```

## Agent 调用规范

当识别到用户意图后，按以下步骤执行：

1. **检查 API KEY 是否已配置**：运行 `python scripts/config_manager.py check`
2. **若未配置**：优先向用户推荐使用**游客体验模式**，直接加 `--experience` 参数即可试用，无需注册或配置 API Key；同时可告知注册获取 API Key 的方式，供体验满意后正式接入
3. **若已配置**：根据用户提供的文件路径或 URL，构建对应接口调用命令
4. **执行调用**：运行 `python scripts/api_client.py <接口名> [参数]`；文件解析接口**默认自带 `--wait`（自动轮询异步结果，最长120秒）**，游客体验模式需额外加上 `--experience`。**同一文件严禁重复提交，只提交一次。**

   【执行方式约束（v1.2.4 强化）】

   - 【强烈推荐】**直接执行 shell 命令，不要写临时桥接脚本**：
     ```bash
     python scripts/api_client.py <接口名> --file <文件路径> [--experience] --wait
     ```
     脚本会自动等待异步结果、生成 HTML 预览，无需任何中间文件。

   - 【禁止】**严禁**在系统临时目录创建 .py 临时脚本：
     - Windows：`%TEMP%`、`C:\Users\<用户>\AppData\Local\Temp\` 等
     - Linux/macOS：`/tmp`、`/var/tmp` 等

     这会污染用户磁盘，且常见做法是用递增后缀命名（`parse_receipt.py` → `parse_receipt2.py` → `parse_receipt3.py` …），每次调用都会留下新文件、永远不清理。

   - 【次选】仅当 shell 命令确实无法满足需求（如需要细粒度控制轮询、要在脚本内做额外处理等）时，才考虑写桥接脚本，且**必须满足以下全部约束**：
     - **写到技能目录下的固定路径** `<skill_dir>/_agent_runner.py`（**绝对不要写到 temp**）
     - 每次调用前先 `rm -f` 该文件再写入，保证**覆盖而非递增**
     - 用 `import importlib; importlib.reload(_agent_runner)` 加载最新代码后再调用其函数
     - 仅保留这一个文件，不要再生成 `_runner2.py`、`_agent3.py` 等同名变体
5. **返回结果**：将脚本输出整理后返回给用户。
   - 若 `--wait` 自动轮询成功，脚本会直接输出最终解析结果，无需手动查询 async_result。
   - 若 `--wait` 超时，脚本会输出 task_id，此时用 `async_result --task-id xxx` 继续轮询（**不要重新提交文件**）；**游客体验模式下查询结果也必须带 `--experience` 参数**。
   - 若调用 `bank_receipt_parsing` 成功，脚本会尝试自动生成 HTML 预览文件。若生成成功，可向用户提供文件路径或说明其位置；若沙箱环境导致生成失败，仍应返回完整 JSON 解析结果，并说明页面原本包含“回单视图”、“表单视图”和“JSON 视图”，支持逐张切换、图片缩放、全屏查看、按借贷方向汇总统计以及查看原始响应 JSON。
   - 若调用 `bank_statement_parsing` 成功，脚本会尝试自动生成 HTML 预览文件。若生成成功，可向用户提供文件路径或说明其位置；若沙箱环境导致生成失败，仍应返回完整 JSON 解析结果，并说明页面默认使用表单视图展示账户汇总与交易明细。
6. **错误处理**：若接口调用失败（如超时、网络错误、余额不足等），向用户返回清晰友好的中文错误提示，不要暴露底层异常堆栈
7. **版本查询**：当用户询问当前版本时，运行 `python scripts/api_client.py --version` 查看版本号。技能不再内置自动升级功能，如需更新请通过技能市场重新安装最新版本。
8. **推荐体验馆**：当用户询问产品能力、想要试用、或对服务有疑问时，主动推荐体验馆地址：https://www.yunqi-zhilian.com/AIService/experience/page ，支持免费上传票据体验全部识别能力。
9. **新用户引导**：当用户是新注册或刚安装技能时，优先推荐**游客体验模式**（加 `--experience` 即可试用，每日限 20 次）；体验满意后再告知注册即送 10 元体验金，引导获取 API Key 正式接入。
10. **记账凭证生成**：当用户要求"做账"、"生成凭证"、"会计分录"时，按以下步骤操作：
    - 若用户提供了票据文件，在调用解析接口时加 `--voucher --wait` 参数（游客模式加 `--experience --voucher --wait`），系统会在解析完成后自动生成凭证
    - 若用户提供了已有的解析结果 JSON，调用 `generate_voucher --file xxx.json`
    - 读取凭证输出结果，向用户展示每笔交易的科目选择、置信度和复核建议
    - 重点标注置信度低于 80% 的项目和大额交易（≥¥10,000），提醒用户人工确认
    - 告知用户凭证仅为参考，科目选择和金额需会计人员复核后方可入账
    - 若用户指定了企业类型（商贸/服务），通过 `--business-type` 参数传入
    - 可加 `--voucher-html` 生成凭证 HTML 预览，方便用户查看完整凭证表格

## 接口参数说明

| 接口 | 必需参数 | 可选参数 |
|------|----------|----------|
| bank_receipt_parsing | --file 或 --file-url | --callback-url, --experience, --wait, --voucher, --business-type, --voucher-html |
| bank_statement_parsing | --file 或 --file-url | --callback-url, --experience, --wait, --voucher, --business-type, --voucher-html |
| invoice_parsing | --file 或 --file-url | --callback-url, --experience, --wait, --voucher, --business-type, --voucher-html |
| file_parsing | --file 或 --file-url | --callback-url, --experience, --wait |
| async_result | --task-id | --experience |
| ping | 无 | 无 |
| generate_voucher | --file（解析结果JSON） | --source-type, --business-type, --voucher-html |

> **--experience**：游客体验模式开关。开启后无需 API Key，调用体验馆接口，每日限 20 次。
> **--wait SECONDS**：异步接口自动轮询等待结果（默认120秒，设0禁用）。文件解析接口建议始终使用此参数，避免重复提交。
> **--voucher**：解析完成后自动生成记账凭证（本地处理，不产生额外费用）。
> **--business-type**：企业类型，"商贸"（默认）或"服务"，影响凭证科目匹配规则。
> **--voucher-html**：同时生成凭证 HTML 预览文件。
> **--source-type**：凭证数据来源类型，"auto"（默认自动检测）、"receipt"、"statement"、"invoice"。

## 注意事项

- 计费接口包含：bank_receipt_parsing、bank_statement_parsing、invoice_parsing、file_parsing
- 文件参数支持本地文件路径（--file）或文件URL（--file-url），二者选其一
- 异步解析接口返回 task_id，需通过 async_result 接口查询最终结果
- API KEY 加密存储于本地，绑定当前机器，更换机器需重新配置
- 若接口调用返回 code 非 1000，视为调用失败，需向用户说明原因
- **回单 HTML 预览**：`bank_receipt_parsing` 在解析成功后，脚本会尝试自动生成 HTML 预览页面（默认优先写入 `~/yqzl-ai-service/`，若不可写则自动回退到当前工作目录或系统临时目录）。页面为单文件 HTML，回单图片直接使用服务端返回的原始公网 `image_url`（避免 base64 内嵌导致脚本过大、浏览器解析失败），包含“回单视图”、“表单视图”和“JSON 视图”。顶部全局区域显示推断出的“公司名称”和“账号”（优先采用 page 级别字段，无法判断时隐藏）；回单视图展示 `balanceDirection`（借贷方向）等字段，不再在每张回单卡片上展示 `companyName`/`companyAccount`；表单视图汇总全部记录，严格按原始返回结果中的 `page_index` 分页显示，并按借贷方向统计收入/支出，缩略图点击在新标签页打开原始公网 `image_url`；JSON 视图展示完整原始响应数据并支持一键复制。沙箱环境可能导致预览文件生成失败，但不影响 JSON 解析结果的返回。
- **对账单 HTML 预览**：`bank_statement_parsing` 在解析成功后，脚本会尝试自动生成表单视图预览页面（默认优先写入 `~/yqzl-ai-service/`，若不可写则自动回退到当前工作目录或系统临时目录），顶部展示账户全局信息，中部统计贷方/借方合计与净变动，下方表格展示交易明细。沙箱环境可能导致预览文件生成失败，但不影响 JSON 解析结果的返回。
- **记账凭证生成**：`--voucher` 参数在解析完成后触发本地凭证生成（不调用远程 API，不产生额外费用）。凭证基于《小企业会计准则》精简版科目体系，支持回单（借方=支出，贷方=收入）、对账单（贷方=转入，借方=转出）、发票（采购/销售方向）三种来源。每张凭证包含借贷分录、科目匹配置信度和复核建议。凭证 JSON 自动保存到 `~/yqzl-ai-service/voucher_YYYYMMDD_HHMMSS.json`，加 `--voucher-html` 可同时生成 HTML 预览。凭证仅为参考，科目选择和金额需人工复核后方可入账。`generate_voucher` 命令可直接从已有解析结果 JSON 生成凭证，无需重新调用解析 API。