企业官网建设流程全解析

做AI应用这几年，我最大的感受是：模型的能力边界，往往不是你prompt写得有多好，而是你喂给它的数据有多干净。很多团队把大把精力花在调prompt、调温度参数上，结果项目真正卡住的却是“数据进不来”。合同还是扫描件，发票还是图片，PDF翻开来全是排得乱七八糟的版面，模型再聪明，读不到内容就是白搭。Dify和PaddleOCR这套组合，恰好把这块短板补上了——一个负责把图片、扫描件变成结构化文本，一个负责把这些文本真正嵌进Agent工作流里，形成可落地的业务闭环。这篇内容我会围绕“为什么做”“怎么设计”“怎么落地”三个层面展开，把集成思路、部署步骤、参数调优和踩坑记录都摊开来讲。如果你正在用Dify搭Agent，或者正头疼“文档怎么喂给模型”，这篇文章应该能帮你省下不少试错时间。

1. 为什么要把OCR能力嵌进Agent工作流

1.1 Agent的“感知层”是最容易被低估的短板

Agent这个词听起来玄乎，拆开看无非是感知、决策、行动三步。决策靠大模型，行动靠工具调用，但感知这一步常常被忽略。所谓感知，就是Agent怎么理解外部世界输入的数据。文本输入还好说，一旦输入是图片、扫描件、非结构化PDF，Agent就变成了睁眼瞎。OCR在这里扮演的角色，相当于给Agent装了一双眼睛，而且这双眼睛不止是“看见”，还要“看懂”。

这个短板之所以容易被低估，是因为很多开发者在搭Demo的时候，输入都是自己准备好的干净文本。比如“帮我写个总结”，输入是一段复制好的文字，Agent当然能跑通。但一旦放到真实业务里，用户上传的是拍照的合同、扫描的票据、传真件，整个流程就断了。很多项目从Demo到生产环境之间那条巨大的鸿沟，其实就是“感知层”没补上。OCR不是锦上添花，而是业务落地的前置条件。

另一个更微妙的问题是，OCR不光是“把图变成字”，更关键的是“把字变成有用的结构”。一张扫描件里，标题、正文、表格、页脚混在一起，如果只是粗暴地把所有文字拼成一段，后面的模型和数据流都会被这个粗糙的输入拖累。所以真正要做的，是基于OCR的版面感知能力，把文档解析成带结构的信息块。这也是为什么PaddleOCR不是简单地做文字识别，而是提供了整套版面分析和结构化输出的能力。

1.2 三类高频场景：票据识别、版面解析、长文档问答

先说票据识别。发票、合同、银行回单这类单据，最大的特点是“字段位置固定、但样本差异大”。不同公司开的发票版式不一样、打印清晰度不一样、盖章会盖住文字。这种场景下，OCR要做的不是“把字识别出来”，而是“把字识别出来之后，落到对应的业务字段上”。比如发票号码、金额、税额，这些字段提取准不准，直接决定财务流程能不能自动化。实际业务里，票据识别往往还要叠加防伪、验真、查重这些环节，OCR是这条链路的第一环，错了后面全错。

再说版面解析。很多PDF不是文本型PDF，而是扫描后合成的图片型PDF，里面可能有表格、图片、多栏排版。单纯把整页文字识别出来还不够，因为表格结构会丢、段落顺序会乱。这个时候需要OCR工具具备版面分析能力，把页面切成标题、正文、表格、页眉页脚，再按阅读顺序拼接。PaddleOCR的PP-Structure就是干这个的，它能输出每个区域的类型和坐标，这个输出对后面的信息抽取特别重要。

最后是长文档问答。比如公司内部的规章制度、产品手册，可能几百页，且都是扫描件。你想让Agent基于这些文档做问答，第一步就是把每一页OCR成文本，再切片进知识库。这个环节的识别准确率，直接决定了后续问答质量的上限。OCR错了，后面RAG检索和生成都不可能对。而且这类场景有个隐蔽的坑：几百页的文档，如果OCR过程不能自动化、不能批量处理，靠人工一页页去纠正，成本高到你会怀疑人生。

2. Dify与PaddleOCR：这套组合为什么成立

2.1 Dify强在把模型能力“工程化”

Dify的价值不在于它拥有某个特别强的模型，而在于它把大模型应用开发过程中那些重复性的工程问题解决了。工作流可视化编排、知识库管理、工具接入、Agent多轮对话、日志追踪，这些能力全部开箱即用。尤其是自定义工具机制，让我可以把任意一个HTTP服务接入到工作流里，和LLM节点、其他工具节点编排在一起。

在这个架构里，Dify更像是一个“中台”。模型可以换、工具可以加、工作流可以改，但整体的骨架和运行机制是稳定的。对于业务团队来说，这意味着很多需求不需要再单独开发一套系统，直接在Dify里调工作流就能完成。比如客户说要做一个“合同审批助手”，如果从零开发一套，从吃饭里挑出饿字都来不及，但在Dify里可能只是把OCR工具、LLM节点、条件分支节点连起来的一条工作流。

Dify还有一个被忽视的优势：它对非技术背景的同事相对友好。可视化编排让产品、运营也能看懂流程长什么样，降低协作成本。至少在我接触过的团队里，Dify很自然地成了技术同学和业务同学之间沟通的桥梁。OCR服务是后端的事情，但“识别出来的文本要怎么流转、低置信度的要不要转人工”，这些逻辑在Dify的工作流画布上一目了然，讨论起来效率高很多。

2.2 PaddleOCR的优势不止是“开源免费”

OCR工具库其实不少，Tesseract、EasyOCR、PaddleOCR是几个常见选择。Tesseract历史悠久，但中文识别效果一般，表格和版面分析能力薄弱。EasyOCR上手快，但对中文场景的优化不如PaddleOCR深入。PaddleOCR的优势在于模型体系完整：检测、方向分类、识别、表格、版面，每个环节都有单独的模型可以替换升级；同时中文场景经过大量真实数据优化，且持续迭代。PP-OCRv4在中文识别上的准确率，日常场景实测下来大部分能到95%以上。

还有一个很实在的优势是部署灵活。PaddleOCR支持CPU推理，也支持GPU加速，模型可以按需裁剪。对于Dify这种需要在线调用的场景，可以把OCR封装成独立的HTTP服务，单独部署、单独扩容，和Dify本身的设计哲学非常契合。模型文件也不大，PP-OCRv4的中文模型压缩后在几MB到几十MB的量级，分发部署都很方便。如果团队有离线部署的需求，PaddleOCR也能比较轻松地跑到内网环境里。

当然，PaddleOCR不是没有缺点。它的依赖库比较多，环境安装偶尔会踩版本坑；文档里的很多示例代码更新得比较快，网上搜到的旧教程可能对不上新版API。但这些属于“学习成本”层面的问题，和它在中文文档处理上的能力优势相比，是完全可以接受的。

2.3 “深度集成”的核心：OCR结果参与Agent决策

很多人误以为集成OCR就是“调个API拿回文本”，实际上浅层集成和深度集成的差别非常大。浅层集成是：用户传一张图，OCR返回文本，然后就没有然后了。深度集成是：OCR返回的结果，包括文本内容、置信度、坐标信息、版面类型，会被结构化成Agent决策的依据。比如识别某张发票的置信度只有0.7，工作流会走人工复核分支而不是直接自动入账；比如表格识别的结构置信度低，就自动转给可视化解析节点再处理一次。

这个设计思路的关键在于：OCR输出的不应该是“死数据”，而应该是“活的信号”。举个例子，当OCR识别出一张票据上的金额是10000，置信度0.99的时候，工作流可以直接进入下一步；但如果识别出金额是10000，置信度只有0.6，那么这单就可能需要人工再看一眼。置信度、坐标、版面类型这些元信息，成了Agent做路由判断的依据，这才是真正的“深度集成”。

我理解“智能文档底座”的含义就在于此：OCR不是一次性工具，而是整个Agent体系里稳定、持续支撑文档理解的基础设施。所有涉及文档数据的能力，都可以建在这层底座之上，而且这个底座能随着模型升级、数据积累越来越强。

3. 集成方案设计：三种路线怎么选

3.1 方案A：HTTP服务包装，Dify自定义工具接入

最推荐的方案是把PaddleOCR封装成一个独立的HTTP服务，然后在Dify里通过自定义工具注册，让工作流里的任意节点都能调用。这个方案的核心优势是解耦：OCR服务可以独立部署、独立扩容，不会因为PaddleOCR的依赖库版本问题影响Dify主体；Dify侧只维护工具的OpenAPI描述，逻辑清晰，后续换OCR引擎也不伤筋动骨。

具体操作上，用FastAPI写一个轻量的服务，暴露一个“接收图片、返回结构化文本”的接口。图片可以用base64传，也可以用URL传。我一开始是用base64，因为Dify的文件对象转base64方便，也不依赖额外的文件存储服务。当然后续如果图片太大，base64会膨胀三分之一左右，那时候可以考虑换成对象存储加URL的方式，减少网络传输压力。

这个方案还有一个额外的好处，就是方便多环境共用。一个OCR服务可以同时给开发环境、测试环境、生产环境使用，只要API鉴权控制好就行。开发阶段甚至可以直接用本地的服务实例，调试起来非常方便。

3.2 方案B：Dify代码节点直调PaddleOCR库

Dify的工作流里有一个“代码节点”，可以直接写Python或JavaScript代码。理论上，你可以在代码节点里import paddleocr，直接调用本机安装的OCR库。这个方案实现最快，适合在本地调试、演示Demo时用。我当时做最小验证的时候就是这么干的，省去了写HTTP服务的步骤，直接在节点里跑通了“图片到文本”的链路。

但我不建议在生产环境这么干。Dify的代码节点执行环境有很多限制：依赖安装要额外配置、并发性能不好控制、执行超时上限不高。而且每次调用OCR都要加载模型到内存，同一个工作流并发超过几个请求就会把机器拖垮。更重要的是，代码节点的逻辑和OCR服务混在一起，出了问题很难排查到底是工作流的问题还是OCR的问题。所以方案B的本质是“快速验证”，不是“生产架构”。

3.3 方案C：离线批量OCR，结果进知识库

第三种思路是完全绕开在线调用：写一个离线脚本，批量把扫描型PDF、图片集识别成文本，然后按照Dify知识库要求的分段格式整理好，一次性导入。适合做历史数据清理、知识库冷启动。这个方案不涉及工作流集成，复杂度最低，但只能做“离线导入”，没法处理用户的实时上传文件。

这个方案在两类场景里特别有价值。一类是历史档案数字化，比如公司过去几年的合同、单据全是扫描件，需要一次性变成可检索的文本；另一类是知识库冷启动，很多团队搭RAG应用，第一步要喂给知识库的资料就是PDF、图片，不可能让用户在线上慢慢传，离线批处理才是常态。

3.4 我的选型结论

我最终采用的是“线上方案A + 线下方案C”的组合。线上实时场景走HTTP服务，保证工作流的响应速度和稳定性；线下历史数据批量处理走离线脚本，减少对在线服务的压力。两个方式并行，各自负责各自的场景，这也是很多实际项目验证过比较稳的架构。

如果你刚起步，我的建议是别一上来就搞太复杂的架构。先在本地把PaddleOCR跑通，确认识别效果满足业务需求；再花半小时用FastAPI包一个HTTP服务；然后在Dify里注册工具、拉通工作流。整个链路一旦通了，后面就是不断调优的过程。不要一上来就想着分布式、异步队列，那都是后续要处理的问题，先把端到端跑通才是最重要的。

4. 实操部署：把智能文档底座一步步搭起来

4.1 第一步：封装PaddleOCR的HTTP服务

先装基础依赖。这里要特别提醒，paddlepaddle和paddleocr的版本必须匹配，我早期就吃过版本不匹配的亏，装了最新版的paddleocr，结果和paddlepaddle的某些算子对不上，跑起来直接报错。稳妥的做法是参照官方文档的版本对应关系来装。

pip install paddlepaddle==2.5.2 pip install paddleocr==2.7.0

我建议把PaddleOCR的初始化和推理单独拆成一个模块，不要在请求处理函数里做模型加载。模型初始化很耗时，加载一次可能要几秒甚至更久，如果每个请求都重新加载，服务基本没法用。正确做法是在服务启动时加载一次，后续所有请求复用这个实例。

import base64 import numpy as np from fastapi import FastAPI from paddleocr import PaddleOCR app = FastAPI() # 服务启动时初始化一次，全局复用 ocr = PaddleOCR( use_angle_cls=True, lang="ch", ocr_version="PP-OCRv4", text_detection_limit_side_len=960, ) @app.post("/ocr") def run_ocr(request: dict): img_base64 = request.get("image_base64") if not img_base64: return {"code": 1, "msg": "missing image_base64"} try: img_bytes = base64.b64decode(img_base64) img_array = np.frombuffer(img_bytes, dtype=np.uint8) img = cv2.imdecode(img_array, cv2.IMREAD_COLOR) result = ocr.ocr(img, cls=True) # 整理成结构化JSON lines = [] for line in result[0]: text = line[1][0] confidence = float(line[1][1]) box = line[0] lines.append({ "text": text, "confidence": confidence, "box": box }) return {"code": 0, "data": lines} except Exception as e: return {"code": 1, "msg": str(e)}

几个关键参数，我实际用下来的经验值：

• use_angle_cls=True，开启方向分类。扫描件经常有轻微歪斜，不开启方向分类的话，识别结果会明显变差。这个参数非常建议开启，带来的速度开销很小。
• lang="ch"，指定识别中文。如果你的业务里有中英混排，可以设置lang="ch"，PaddleOCR会同时处理中英文。
• text_detection_limit_side_len=960，限制检测最长边。太长的图会被等比缩放，识别速度和准确率之间取平衡。对于A4纸扫描件，这个值够用；如果是超长截图，需要手动切分。
• rec_batch_num，默认是6，如果显存充足可以调大，提高吞吐。CPU环境下不建议调太大，反而会影响单次请求的响应速度。

返回结果不要直接用PaddleOCR的原始输出格式，那是一个多层嵌套的list，结构复杂、可读性差，不利于Dify工具解析。最好在服务侧先整理成结构化JSON，包含字段：text、confidence、box等。这一步做得好，后面Dify里的数据清洗会轻松很多。

关于服务部署，可以用gunicorn启动多进程，配合一台CPU机器基本能满足中小规模并发。如果图片量很大，建议上GPU，在PaddleOCR构造函数里传入device="gpu"即可。我的做法是先用CPU版本跑通流程，再用GPU提升吞吐。

4.2 第二步：在Dify里注册自定义工具

Dify的自定义工具支持OpenAPI规范。在Dify的控制台找到“工具”菜单，选择“自定义工具”，填写OpenAPI Schema，Dify会自动识别出接口定义。这里有个小技巧：先在本地用Swagger等工具验证一下Schema有效性，再去Dify里填，避免反复提交报错。

下面是我实际用的Schema简化版：

openapi: 3.0.0 info: title: PaddleOCR Service version: 1.0.0 paths: /ocr: post: summary: 图片OCR识别 operationId: runOcr requestBody: required: true content: application/json: schema: type: object required: - image_base64 properties: image_base64: type: string description: 图片base64编码 responses: '200': description: OCR结果

注册完成后，Dify会把这个工具作为可调用的节点出现在工作流编辑器里。之后在工具节点里配置参数，大部分情况下只需要把上游节点传给它的文件转成base64传进来。

这个过程中最容易踩的坑是图片传递方式。Dify工作流里用户上传的图片，在系统内部有文件引用，不能直接当base64用。我是在工作流里先加一个“代码节点”，接收文件对象，读取内容转成base64字符串，再传给OCR工具。这一步非常关键，很多人卡在这里半天才发现是数据类型不匹配。

4.3 第三步：编排“文档结构化”Agent工作流

整个过程可以拆成下面几个节点：

1. 开始节点：接收用户上传的图片或PDF文件
2. 代码节点：把文件转成base64，并做简单的格式判断
3. 工具节点：调用PaddleOCR服务，拿到结构化文本结果
4. 代码节点：清洗结果，过滤低置信度内容，拼接字段
5. LLM节点：把清洗后的文本按预设模板抽取关键信息，输出JSON
6. 条件分支节点：根据OCR置信度和LLM抽取的字段完整性，判断走自动入库还是人工复核
7. 结束节点：返回结构化结果和状态

这个流程里，LLM节点不是必须的。如果只是纯提取文本，直接让OCR输出结果即可。但如果你做的是票据识别之类的任务，需要从识别文本里再抽出“开票日期”“税额”“收款方”这类结构化字段，那一定要加一个LLM节点做二次抽取。OCR负责把文字“读”出来，LLM负责把文字“理解”成业务字段，两者配合，准确率会高很多。

LLM节点的prompt我建议这样写：把OCR的返回文本原样给模型，同时在prompt里给出目标字段集合和输出格式约束。最好再加一个“如果文本中找不到该字段，返回空字符串，不要猜测”的约束，能明显减少模型幻觉。

你是一个文档信息抽取助手。下面是OCR识别出的文档文本，请从中抽取以下字段： - 发票号码 - 开票日期 - 合计金额 - 税额 只输出JSON格式，不要其他解释。如果文本中没有某个字段，输出空字符串，不要猜测。 文本： {{ocr_text}}

4.4 第四步：实测调参

实操下来，有几个参数直接影响效果：

• 文本检测的阈值，默认是0.3。如果图片质量比较差，可以调高到0.4左右，减少误检框，但要注意太高会漏掉低对比度的文字。
• 长图片处理：如果是长截图或者长表格，建议把图片按高度切成几段分别识别，再拼接结果。PaddleOCR直接处理超长图，识别精度会明显下降。
• 方向分类对歪斜文档非常重要，千万不要为了省那点推理时间关掉它。

还要说一个容易被忽略的大坑：token长度。OCR一页A4纸的文字量大概在800到1500字左右，如果是表格、票据，识别出来的内容转换成JSON会更长。这些文本如果直接塞给LLM节点，很容易超context。我的做法是：先按业务需要做字段裁剪，只把关键字段传给LLM，或者用“滑动窗口”分片处理。这个环节规划好了，工作流才不会动不动就超限报错。

5. 集成之后：业务效率到底提升了多少

5.1 处理时效维度

我在一个模拟项目X里做过对比。以前处理一批票据，需要人工逐张录入，一张平均3到5分钟，录入完还要二次核对。接入OCR工作流后，一张票据从上传到输出结构化字段，正常在5到10秒内完成。就算加上人工抽检环节，整体效率提升也在十倍以上。而且时间主要花在网络传输和模型推理上，人工几乎不参与。

这个差距在那些“不可能完成”的场景里更明显。比如高峰期集中上传一百张发票，以前意味着一个人一整天坐在那里录数据，现在工作流自动处理，系统会排队跑完。人只需要在最后看一眼置信度标记出来的可疑项就行。

5.2 准确率维度

准确率要分开看：纯OCR字符准确率，和字段级提取准确率。PP-OCRv4在打印体中文的字符准确率，实测正常清晰图片在95%以上。字段级准确率，也就是“金额、日期、发票号这些关键字段提取得对不对”，取决于OCR识别和LLM抽取两段，整体在90%左右。

注意，90%这个数字单独看好像不够高，但关键在于兜底机制。不要指望OCR百分百准，而是要在工作流里设计好“低置信度转人工”的链路。识别置信度低于阈值、字段缺失、格式校验失败，这些情况都自动转人工复核队列。这样整体业务的可靠性，不是依赖单一环节的准确率，而是靠流程设计来兜底。

5.3 复用性维度

一个PaddleOCR服务接入后，可以被Dify里多个不同的Agent工作流复用。合同关键信息提取用一个工作流，发票验真用另一个工作流，但底层调的是同一个OCR服务。以后OCR模型升级了，替换服务即可，所有上层工作流自动生效。

这也是“底座”这个词的含义：它不是某个具体业务的一次性工具，而是可以支撑长期、多场景演进的底层能力。实际项目里，你会发现一旦文档底座稳定了，很多新的业务需求会变得特别简单。比如“把客户发来的营业执照信息录入系统”，听起来是个新需求，但其实只是把OCR工具和另一个LLM节点连起来，半天就能搞定。

6. 常见问题与排查技巧实录

6.1 中文识别乱码或丢字

最常见的原因不是模型问题，而是图片编码和传输问题。base64字符串里有换行符，或者图片压缩过度，都会导致识别效果异常。排查方法：在OCR服务端加日志，把接收到的图片base64前100个字符打出来，确认数据完整性。另外，如果识别结果里繁体字、生僻字经常错，可以考虑在PaddleOCR初始化时指定rec_model_dir，加载更大的识别模型。

6.2 表格识别错位

PaddleOCR的表格识别有两种方式：一种是纯文本表格解析，输出HTML结构；另一种是结合版面分析定位单元格。前者速度快，但复杂表格容易错位；后者更稳，但速度慢。我的经验是，结构简单的二维表用前者，带合并单元格、跨行跨列的表用后者。Dify工作流里可以把表格识别单独做一个工具接口，按业务需求分别调用。

6.3 Dify工具调用超时

HTTP服务部署后常见的问题是Dify那边调用超时。原因一般是OCR服务处理时间长于Dify的默认超时时间。解决办法有两个方向：一是优化OCR服务响应，比如图片压缩、模型裁剪、增加并发worker；二是把耗时操作改成异步任务，Dify这边轮询结果。中小团队先做前者就够了，真扛不住了再上异步方案。

6.4 CPU还是GPU，怎么选不纠结

很多人一上来就纠结算力。我的建议是：先评估业务量。每天的调用量如果在几千次以内，一台8核16G的CPU机器完全够用。每次调用大概耗时1到3秒，并发控制在5个以内比较稳。如果单张图的延迟要求压到1秒以内，或者并发需求到了20以上，再上GPU。GPU建议用T4及以上的卡，显存8G起步，这是性价比最高的方案。别在项目第一天就花大钱买GPU，先让业务跑起来再说。

我自己在实际项目中反复调整过好几轮，最后沉淀下来的一点体会是：把OCR接进Agent工作流的难点，从来不在OCR本身的识别率，而在于怎么让OCR的输入、输出和Agent的工作流顺畅衔接。输入侧要处理文件格式与编码，输出侧要设计结构化的数据契约，中间还要考虑超时、并发、置信度这些工程细节。把这些基础问题解决掉，OCR才是真正“长”在了工作流里，而不是一个游离在外的API。

后面如果再扩展，我会往两个方向走。一是把PaddleOCR的版面分析结果进一步用于文档自动分类，让Agent能先判断“这属于什么类型的文档”再决定走哪条处理分支；二是把OCR识别结果回流到知识库，形成文档资产的长期沉淀。这套底座越用价值越大，数据越积累越聪明。希望这篇内容能帮你少走点弯路，早日跑通自己的文档工作流。