企业官网建设流程全解析

TextIn xParse 上架 WorkBuddy 后，智能文档处理这件事的门槛被明显拉低了一大截。以前处理 PDF、图片里的表格和公式，要么装本地解析工具，要么写脚本调接口，要么手动复制粘贴再排版。现在 WorkBuddy 里装上 xParse 这个技能，用一句话就能把“上传文档 → OCR 识别 → 版面解析 → 转成 Markdown/HTML → 进知识库”整条链路串完。这篇文章不讲虚的，直接拆解 TextIn xParse 在 WorkBuddy 里的定位、怎么把它配成可用技能、怎么用一句话触发完整解析流程，以及接入接口和批量任务时需要注意哪些问题。

先看这个组合最值得关注的地方在哪里。TextIn xParse 是合合信息旗下的智能文档解析模型，主打 PDF、图片、扫描件里的版面还原，包括段落、表格、公式、页眉页脚、阅读顺序这些细节。WorkBuddy 则是一个 AI Agent 工作台，能装各种 skill，把大模型、工具、数据源串成自动化流程。两者结合以后，xParse 不再是孤立的解析工具，而是变成一个可以“随叫随到”的文档处理能力。

不用关心显存、不用关心显卡驱动。官方是以云端 API 和平台技能的形式提供，所以不存在本地部署时的 CUDA、PyTorch、显存占用这些硬门槛。你只需要有一个 WorkBuddy 账号，把 TextIn xParse 技能加进来，然后给它一句话任务描述。

本文会带读者完成这几件事：先理解 xParse 能解析什么、适合什么场景；然后在 WorkBuddy 里配置好 TextIn xParse 技能；接着用自然语言触发几次真实解析任务，覆盖 PDF 转 Markdown、表格识别、公式抽取和批量处理；再补充接口调用和批量任务的设计思路；最后给出容易踩坑的地方和一套可复用的处理规范。

1. 核心能力速览

从能力速览能看出来，这个组合最核心的定位是：把高质量的文档结构化解析能力，通过对话式 Agent 开放给非技术用户。过去要写 Python 脚本才能实现的 PDF 转 Markdown，现在在 WorkBuddy 里说一句“把这份 PDF 解析成 Markdown 表格齐全”即可完成。

2. 适用场景与使用边界

2.1 适合谁用

• 知识库搭建者：需要把大量 PDF、Word、图片导入知识库，希望保留原文结构和表格。xParse 解析后的 Markdown 特别适合做向量化前的清洗，能明显提升检索准确率。
• 研究分析类用户：经常看论文、研报、财报，需要把 PDF 里的公式、图表、多栏排版还原成可编辑文本。通用 OCR 只出纯文本，xParse 这类版面解析模型能还原阅读顺序和层级关系。
• 非技术运营人员：不会写代码，也不想学接口调用。WorkBuddy 的对话式交互让文档处理变成“发指令”而不是“写脚本”。
• 开发者的前置处理环节：即使最终要写代码，也可以先在 WorkBuddy 里用 xParse 验证解析效果，确定提示词和输出格式，再进入接口批量阶段。

2.2 能解决什么问题

这里把“通用 OCR”和“版面解析”分开看。普通 OCR 解决的是“图片里有什么字”，xParse 这类模型解决的是“这段文字是标题、表格还是公式，它在页面上的坐标和阅读顺序是什么”。后面这个能力才是文档自动化处理真正需要的。比如一份带有复杂表格的 PDF，纯文本 OCR 会把表格里的内容按行打散，丢失列关系和层级；xParse 能把整个表格结构还原成 Markdown 表格，后续直接进数据库或知识库。

WorkBuddy 最大的价值是把零散能力编排成流程。一个文档解析技能只能解析单个文件，但配上 WorkBuddy 的 skill 机制后，用户可以说“把 inputs 文件夹里所有 PDF 解析成 Markdown，然后汇总成一个清单”，这就是从工具到自动化流程的跨越。

2.3 不适合什么场景

• 对数据隐私要求极其严格、必须本地离线处理的场景，不适合直接用云端 API。这类场景需要评估合合信息的企业私有化部署方案。
• 手写体密集、严重倾斜、低分辨率的历史扫描件，任何文档解析模型都会遇到效果瓶颈。不能说“一个模型解决所有 OCR 问题”。
• 需要极低延迟的实时解析场景。云端 API 有网络开销，单次解析耗时通常在秒级到十秒级，不适合毫秒级在线交互。

2.4 合规提醒

涉及合同、票据、身份证、人像照片、内部研发文档时，先确认自己有没有合法处理权限。把文档上传到第三方模型解析，本质上是一次数据外发，需要遵守公司数据安全规范和个人信息保护要求。涉及版权材料时，解析后如果重新发布或商用，还需要确认授权范围。

3. 使用前准备

使用 WorkBuddy + TextIn xParse 前，需要整理一份清单。

3.1 WorkBuddy 账号准备

• 访问 WorkBuddy 官网注册账号。从材料看，WorkBuddy 有网页版、Windows 版、Linux 版和麒麟版，也就是说它在办公电脑、服务器以及国产化环境里都有对应的客户端。
• 登录后先看“技能（Skill）”市场或技能管理入口，确认当前账号是否已经开放 TextIn xParse。
• 如果你需要使用 DeepSeek 等外部大模型能力，可以提前准备模型 API Key，WorkBuddy 支持接入 DeepSeek，这个在后面的技能编排里会用到。

3.2 TextIn xParse 可用性确认

• 确认 TextIn xParse 技能是否已经在 WorkBuddy 上架。如果还没出现在技能市场，可以直接到 TextIn 官网注册账号，获取 API Key 后手动配置自定义技能。
• TextIn 平台本身提供文档解析 API，无论 WorkBuddy 里是否直接上架，你都可以通过自定义 skill 的方式把 xParse 的能力接进来。

3.3 测试文档准备

准备几类典型文档，覆盖不同解析难度：

样本文件不要太大。首次测试控制在单文件 10MB 以内，页面数控制在 20 页以内，方便快速观察效果和排查问题。

3.4 输出目录准备

即使是在 WorkBuddy 对话式场景里，也要养成目录管理的习惯：

data/ ├── inputs/ # 待解析文档 ├── outputs/ # 解析结果 │ ├── markdown/ │ ├── html/ │ └── json/ ├── logs/ # 批处理运行日志 └── archive/ # 已处理文档归档

这套目录结构在后面接 API 和批量任务时会直接用上。

4. 在 WorkBuddy 中启用 TextIn xParse 技能

4.1 方案一：直接从技能市场添加

如果你的 WorkBuddy 账号已经开放 TextIn xParse：

1. 打开 WorkBuddy，进入技能市场。
2. 搜索“TextIn”或“xParse”。
3. 点击添加，确认授权。
4. 添加完成后，新建一个对话或工作台页面，在技能列表里启用 TextIn xParse。

启用后在对话里输入指令，WorkBuddy 会调用 xParse 完成解析，并把结果返回给后续流程。

4.2 方案二：用 TextIn API 配置自定义技能

如果平台内还未直接上架，可以通过自定义 skill 的方式封装。你需要：

1. 注册 TextIn 账号，创建应用，获取 API Key。
2. 在 WorkBuddy 里新建自定义技能/工作流，添加“调用 HTTP API”节点。
3. 配置 TextIn 文档解析接口的请求地址、请求头、请求体。
4. 把文档上传节点和 API 调用节点连接起来。

下面是这个自定义技能里 API 调用的通用配置模板，实际请求地址和参数名需要以 TextIn 官方文档为准：

# 伪代码：在 WorkBuddy 自定义技能中，HTTP 请求节点配置示例 POST /api/v1/document/parse Host: <TextIn API 地址> Authorization: Bearer <你的 API Key> Content-Type: multipart/form-data

{ "file": "<上传的文件流>", "parse_mode": "auto", "output_format": "markdown", "ocr": true, "table_recognition": true, "formula_recognition": true }

这里要强调一下：这些参数只是常见解析请求的结构示例，不代表 TextIn 的真实接口字段。接入前一定要打开 TextIn 官方接口文档核对。做技术集成时最忌直接抄网上的示例参数，接口版本更新后很容易踩坑。

4.3 用一句话触发完整流程

在 WorkBuddy 对话窗口里，输入类似下面的自然语言指令：

请解析这份 PDF，输出 Markdown 格式，保留表格结构，把结果保存到 outputs/markdown/ 目录。

WorkBuddy 会解析这条指令，自动识别文件、调用 xParse、导出结果。这就是“一句话完成智能文档处理全流程”的实际体验。如果你想让指令更稳定，后期可以把这类高频命令写成一个自定义指令模板，后面单独讲。

5. 功能测试与效果验证

技能配置完，下一步就是验证解析效果。下面给出四种核心测试任务和判断标准。

5.1 测试任务一：PDF 转 Markdown

测试目的：验证基础文档解析、标题层级、段落顺序和列表结构。

输入：一份 5 页左右的纯文字 PDF。

操作步骤：

1. 在 WorkBuddy 对话中上传 PDF。
2. 输入指令：

   用 TextIn xParse 解析这个 PDF，输出 Markdown，保留标题层级。

3. 等待解析完成，检查输出文件。

预期结果：

• 一级标题、二级标题、正文段落层级正确。
• 多栏排版的阅读顺序还原正确，而不是“从左栏读到右栏再从右栏读回左栏”。
• 输出结果中不包含页眉页脚等装饰性信息（如果模型支持过滤）。

判断是否成功：对照原 PDF 的目录结构，看 Markdown 里的标题编号和正文顺序是否一致。

常见失败原因：

• 原文本身是扫描件，没有 OCR 步骤，导致抽取不到文字。
• 文档排版过于复杂，阅读顺序被错乱。
• 大文件超时或超出页数限制。

5.2 测试任务二：复杂表格还原

测试目的：验证表格结构还原能力。

输入：一份包含合并单元格、跨行表头、多列表格的财务报表或库存表 PDF。

操作步骤：

1. 上传文件。
2. 输入指令：

   把 PDF 中的表格全部还原成 Markdown 表格，不要丢列。

3. 检查结果。

预期结果：

• 原表格的列数、行数、表头层级一一对应。
• 单元格内换行、数字千分位、百分比符号保留。
• 合并单元格在 Markdown 里以可接受的方式表达。

判断是否成功：拿原 PDF 第 3 页的复杂表格和 Markdown 输出逐列比对，重点看总列数和跨行表头。

常见失败原因：

• 表格有线框断裂，模型识别成多个表格。
• 表头合并跨行时，Markdown 生成逻辑丢失层级关系。

5.3 测试任务三：公式识别

测试目的：验证论文场景的公式抽取能力。

输入：一份带有数学公式的论文 PDF。

操作步骤：

1. 上传文件。
2. 输入指令：

   解析论文，把公式转成 LaTeX。

3. 检查公式部分。

预期结果：

• 行内公式和独立公式都能被识别。
• 公式转成 LaTeX 后，符号、上下标、分数结构可读。

判断是否成功：随机抽 5 个公式，用 LaTeX 渲染后和原公式对比，结构是否一致。

常见失败原因：

• 公式字号过小或印刷质量差。
• 复杂矩阵、多行公式识别不完整。

5.4 测试任务四：批量文档解析

测试目的：验证多文件场景下的任务编排能力。

输入：一个文件夹，包含 5 个不同格式的 PDF。

操作步骤：

1. 在 WorkBuddy 中创建一个批处理任务，选择 TextIn xParse 技能。
2. 输入指令：

   把 data/inputs/ 下所有 PDF 解析成 Markdown，按原文件名保存到 outputs/markdown/。

3. 设置好输入目录、输出目录和错误处理方式，启动任务。
4. 查看运行日志，确认每个文件都被处理。

预期结果：

• 每个 PDF 生成一个对应的 Markdown 文件。
• 如果某个文件失败，任务不中断，记录到日志后继续处理下一个。
• 输出文件与输入文件一一对应。

判断是否成功：检查 outputs/markdown/ 下有 5 个 Markdown 文件，且每个文件的解析内容与对应 PDF 一致。

常见失败原因：

• 文件名包含特殊字符，导致保存路径错误。
• 单个文件超过接口大小限制。
• 批量任务缺少失败重试机制，一个文件失败导致整个流程卡住。

6. 接口 API 与批量任务

对话式调用适合体验和交互验证，但真正的工程化场景还是要走 API。TextIn xParse 本身是 API 服务，理解它的接口方式，才能在 WorkBuddy 之外构建更灵活的自动化流程。

6.1 接口启动方式

从产品形态看，TextIn xParse 是云端 API 服务，不需要自己部署服务进程。开发者只需要：

1. 在 TextIn 平台创建应用。
2. 获取 API Key。
3. 按官方文档调用文档解析接口。

6.2 Python 调用通用模板

下面是调用文档解析接口的通用模板，目的是演示请求结构和异常处理思路，实际接口路径、请求头、返回字段要替换为 TextIn 官方文档中的真实值：

import requests import json API_URL = "https://<TextIn API 域名>/api/v1/document/parse" API_KEY = "你的 API Key" def parse_document(file_path, output_format="markdown"): headers = { "Authorization": f"Bearer {API_KEY}" } # 实际接口字段以官方文档为准，这里仅展示结构 data = { "output_format": output_format, "ocr": "true", "table_recognition": "true" } with open(file_path, "rb") as f: files = {"file": (file_path.split("/")[-1], f)} response = requests.post(API_URL, headers=headers, data=data, files=files, timeout=120) if response.status_code == 200: return response.json() else: raise Exception(f"解析失败: {response.status_code}, {response.text}")

if __name__ == "__main__": result = parse_document("./data/inputs/sample.pdf") print(json.dumps(result, ensure_ascii=False, indent=2))

6.3 markitdown 风格的补充思路

如果你的工作流里已经用了微软开源的 markitdown 这类文档转 Markdown 工具，可以思考两者怎么配合。markitdown 的优势是免费、开源、支持多格式，缺点是复杂版面解析能力有限，表格和公式还原不如专门的版面解析模型。工程上的常用策略是：

• 普通 Office 文档先走 markitdown，速度快且免费。
• 复杂 PDF、扫描件、论文走 xParse，质量更高。

# markitdown 安装命令（补充知识，非本项目必需） pip install markitdown

在 WorkBuddy 技能编排时，也可以设计成：先判断文件类型，PDF/图片走 xParse，Office 文档走 markitdown。这样能把成本和效果做一个平衡。这里需要说明，项目团队实际上把两个工具看作互补，这也是当前文档解析落地工程里比较成熟的思路。

6.4 批量任务设计

批量解析的核心不止是“循环调用接口”，而是要做到可控、可观测、可重试。

批量处理最小设计：

import os import time import json from concurrent.futures import ThreadPoolExecutor, as_completed INPUT_DIR = "./data/inputs" OUTPUT_DIR = "./data/outputs/markdown" LOG_FILE = "./data/logs/batch.log" def process_one(file_name): file_path = os.path.join(INPUT_DIR, file_name) # 这里调用上面实现的 parse_document 函数 # 实际业务中需要补充重试逻辑 result = parse_document(file_path) output_path = os.path.join(OUTPUT_DIR, file_name.replace(".pdf", ".md")) with open(output_path, "w", encoding="utf-8") as f: f.write(result.get("markdown", "")) return file_name, True def batch_run(): files = [f for f in os.listdir(INPUT_DIR) if f.lower().endswith(".pdf")] with ThreadPoolExecutor(max_workers=3) as executor: future_map = {executor.submit(process_one, f): f for f in files} for future in as_completed(future_map): fname = future_map[future] try: fname, ok = future.result() with open(LOG_FILE, "a", encoding="utf-8") as log: log.write(f"{time.strftime('%Y-%m-%d %H:%M:%S')} SUCCESS {fname}\n") except Exception as e: with open(LOG_FILE, "a", encoding="utf-8") as log: log.write(f"{time.strftime('%Y-%m-%d %H:%M:%S')} FAILED {fname}: {str(e)}\n") if __name__ == "__main__": batch_run()

批处理注意点：

• 并发数不要太高，先设 3 到 5，观察接口响应时间和错误率。
• 增加失败重试，失败的文件单独记录，二次重试。
• 已经解析成功的文件跳过，避免重复消耗额度。
• 日志记录包括时间、文件名、成功/失败、错误信息、耗时。

6.5 curl 调用示例

如果你想在 shell 脚本或 CI 里集成，可以这样用：

# 以实际 API 文档地址为准，下面仅展示结构 curl -X POST "https://<TextIn API 域名>/api/v1/document/parse" \ -H "Authorization: Bearer YOUR_API_KEY" \ -F "file=@./data/inputs/sample.pdf" \ -F "output_format=markdown" \ -F "ocr=true"

响应中通常包含解析状态和结果数据，具体字段请查阅官方文档。

7. 性能与成本观察

7.1 如何判断解析质量

解析质量不能只看文字识别准不准，还要看版面结构还原度。重点观察这几个维度：

• 阅读顺序：多栏 PDF 的段落是否按逻辑连续排列。
• 表格层级：合并单元格、表头、跨页表格是否一致。
• 公式结构：LaTeX 是否可直接编译。
• 多余元素：页眉页脚、页码、水印是否被过滤。

7.2 影响解析时间的因素

• 文件页数：页数越多耗时越长，响应时间通常近似线性增长。
• 表格密度：复杂表格会显著增加版面分析耗时。
• 是否 OCR：扫描件比电子版 PDF 多一步 OCR 处理，耗时成倍增加。
• 是否启用公式识别：公式识别是全流程中最重的计算环节之一。

7.3 成本控制建议

• 先用小样本测试效果，再投入全量解析。
• 批量任务设置每日额度上限，防止脚本死循环产生巨额费用。
• 对已经解析过的文件做幂等处理，比如根据文件 MD5 判断是否已经解析。
• 在 WorkBuddy 里设定技能调用范围和频率限制。

8. 常见问题与排查方法

9. 最佳实践与使用建议

9.1 第一次使用时先小规模验证

不要一上来就解析几百个文件。先挑 3 到 5 个不同类型的文档测试，确认解析效果符合预期再扩大规模。这个习惯能帮你省下大量 API 调用费。

9.2 把常用指令固化成 WorkBuddy 自定义指令

如果每天都要执行同样的解析流程，在 WorkBuddy 里把这些指令保存成自定义指令模板。比如：

【PDF 解析标准流程】 1. 将 PDF 上传到 data/inputs/ 2. 用 TextIn xParse 解析，输出 Markdown 3. 保留表格和公式，去掉页眉页脚 4. 保存到 outputs/markdown/，以原文件名命名 5. 完成后输出文件清单

以后每天只需要一句话：“执行 PDF 解析标准流程”。这也是 WorkBuddy 里自定义指令的典型用法。

9.3 模型和格式配合使用

复杂版面优先让 xParse 处理，普通文本直接用轻量工具。合理的流程是“文件类型判断 → 选择解析器 → 后处理清洗”。这个思路在 WorkBuddy 中可以用条件判断节点实现，也可以通过外部脚本实现。

9.4 保留原始文件与解析结果的对应关系

输出文件命名时保留原始文件名，最好再加一个映射文件，记录“原文件路径 → 输出文件路径 → 解析时间 → 是否成功”。没有这个映射，批量解析完成后很难排查问题。

9.5 批量任务必须加日志和失败重试

批处理跑 100 个文件，出现 5 个失败是正常现象。失败原因可能是文件损坏、格式不支持、接口临时限流。正确做法是：

• 失败文件不中断整个任务。
• 将失败原因记录到日志。
• 完成第一轮后，对失败文件做重试。
• 重试仍失败的，单独归档，方便人工处理。

9.6 注意隐私和授权

对内部文档、客户合同、个人证件图片做解析时，先确认数据是否允许发送到第三方平台。重要文件建议在解析前进行脱敏处理。涉及人脸、身份证号、银行卡号等信息时，不要随意上传。解析完成后，如果结果被用于商用发布，还要确认原文档的版权授权。

9.7 接口服务要限制访问范围

如果自己用 Python 封装了 xParse 接口服务，不要直接暴露到公网。设置访问 IP 白名单或请求鉴权，避免接口被恶意刷量、产生高额费用。

9.8 发布或商用前做效果复核

自动解析的结果不能直接拿来发布。批量解析后抽检 10% 到 20% 的文档，重点看表格和公式是否失真。内容发布场景下，错误表格带来的风险往往比漏掉一个字符更大。

10. 总结与下一步

TextIn xParse 上架 WorkBuddy 这件事，把“文档解析”这个专业能力变成了 Agent 世界里的一个普通技能。最值得立刻尝试的是那个核心场景：上传一份带复杂表格的 PDF，说一句话，得到结构完整的 Markdown。

首先建议验证的功能是PDF 转 Markdown 的基础流程和复杂表格还原。这两个功能覆盖了绝大多数知识库和办公文档处理需求，也是最能体现 xParse 相比传统 OCR 价值的地方。最容易踩的坑是：扫描版 PDF 没开 OCR、表格太复杂导致行列错乱、批量任务没有失败重试。这三件事只要提前注意，大部分问题都可以避免。

后续可以继续扩展的方向有三个：

一是把 WorkBuddy 里的解析结果接入 DeepSeek 等大模型，形成“解析 → 清洗 → 向量化 → 知识库问答”的完整链路。WorkBuddy 本身支持接入 DeepSeek，xParse 负责把文档变成高质量文本，大模型负责理解，这个组合能让本地文档问答系统的准确率明显提升。

二是通过 MCP 的方式直接访问数据库。WorkBuddy 支持通过 MCP 接入数据库，解析出来的结构化表格可以直接写入数据库表，省掉中间的人工搬运环节。比如把财报 PDF 里的三张表自动写进数据库，后续就直接用 SQL 查询了。

三是结合 WorkBuddy 搭建个人的文档自动化工作台。除了 xParse，还有很多 skill 可以组合。文档解析只是入口，后面接总结、翻译、摘要、邮件发送，就是完整的文档处理流水线。从一套工作台出发，逐步加技能，就能建起一个直接提高干活效率的日常系统。

一句话总结：TextIn xParse 负责把万变文档变成结构化数据，WorkBuddy 负责把结构化数据变成自动化流程。两件事合在一起，文档处理就是动动嘴的事了。