之前在做“文档解析 → 向量化 → RAG 问答”这条链路时最头疼的其实是第一步文档解析。普通 PDF 直接用文本抽取遇到扫描件、拍照图、复杂表格就全部失效传统 OCR 虽然能出文字但又把标题层级、表格结构、代码块全部拍平后续分块和召回质量很难保证。最近把 DeepSeek-OCR 接入到自己的私有知识库流程后整套体验提升了一个档次它不仅能把图片和 PDF 转成文字还能直接输出结构化的 Markdown 文本标题、表格、公式、代码块都保留得像原始版式一样。这篇文章就把我用 DeepSeek-OCR 从环境搭建、模型部署、Python 调用到 RAG 知识库接入的完整过程记录下来顺便聊一聊 LoRA 微调的原理和实战思路。文章适合两类读者想快速上手 DeepSeek-OCR完成本地部署和调用解决“扫描版 PDF / 图片类文档无法解析”问题的开发者。打算把 OCR 结果接入 RAG 知识库或者对 LoRA 微调感兴趣想了解一套完整技术链路的新手。文章内容较长建议先收藏再跟着一步步操作。下面我们直接开始。1. DeepSeek-OCR 是什么先搞清楚应用场景1.1 传统 OCR 到底少做了什么OCR 的全称是 Optical Character Recognition即光学字符识别。它解决的核心问题是把图片中的文字转换成可编辑的文本。过去我们常用的 OCR 方案基本思路是“目标检测 字符分类”先定位图片里的文字区域再逐个识别字符最后按顺序拼接。对于干净的白底黑字文档这种方式没有问题但遇到下面的场景传统 OCR 就很容易翻车扫描版 PDF 带有页眉页脚、分栏、标题层级。文档中包含表格传统 OCR 只能把文字按行输出表格单元格的对应关系全部丢失。文档中包含代码块、公式、流程图传统 OCR 无法还原代码缩进和公式结构。图文混排、背景色复杂的宣传页或产品手册识别结果顺序混乱。也就是说传统 OCR 的输出是“一坨文字”而不是“一份文档”。在做知识库、RAG、文档结构化等后续处理时这种扁平输出会非常吃力。1.2 DeepSeek-OCR 解决什么问题DeepSeek-OCR 是 DeepSeek 团队开源的 OCR 模型。它的核心特点是输入一张图片输出一段结构化的 Markdown 文本。它把 OCR 任务建模成了“从图像到结构化文本”的生成任务。模型的输出不仅包含文字内容还会加上 Markdown 语法标记比如#、##表示标题层级。|表示的表格结构。$$包裹的公式块。-或1.表示列表。也就是说同样的图片传统 OCR 输出的是纯文字而 DeepSeek-OCR 输出的是可以直接交给后续程序使用的“半成品文档”。这对于 RAG 知识库向量化、内容解析、自动化归档等场景都非常友好。1.3 DeepSeek-OCR 的典型应用场景从我自己的实践来看DeepSeek-OCR 最值得落地的场景有以下几类扫描版 PDF 转 Markdown把纸质书籍、扫描合同、历史档案批量转换为结构化 Markdown 文档。表格识别与结构化财务报表、报销单、调查问卷直接还原为 Markdown 表格后续入库统计更方便。代码截图转代码块把 IDE 截图、技术文档截图中的代码还原为可复制的代码块。RAG 知识库文档预处理作为 RAG 链路中的“文档解析模块”先用 OCR 把非文本型 PDF 转 Markdown再分块、向量化、入库。多模态文档挖掘包含图片、图表、截图的网页或资料可以通过 OCR 先粗提取一遍再做语义分析。需要说明的是DeepSeek-OCR 是一个通用 OCR 模型不是对话式多模态模型。它擅长“看懂图片并输出结构化文字”但如果你希望它像问答模型一样“看图聊天”那不是它的定位。2. DeepSeek-OCR 环境准备与依赖安装2.1 硬件与系统环境说明DeepSeek-OCR 本质是一个深度学习模型推理时需要 PyTorch 环境。可选的运行方式有 GPU 和 CPU 两种GPU 环境推荐 CUDA 驱动已装好显存 8GB 以上体验比较好能跑 bf16 或 fp16 半精度推理。CPU 环境可以运行但速度会慢很多。对于大尺寸图片单张推理可能需要几十秒到数分钟。本文示例使用的环境以 Linux NVIDIA GPU 为主但 Windows 和 macOS 的步骤基本一致核心差异只在 PyTorch 安装命令上。2.2 创建 Python 虚拟环境为了避免不同项目的依赖冲突推荐使用 conda 创建独立环境。Python 版本建议 3.10 或更高。conda create -n deepseek_ocr python3.10 -y conda activate deepseek_ocr2.3 安装 PyTorch 与相关依赖PyTorch 的安装命令需要根据你的 CUDA 版本选择。建议先去 PyTorch 官网生成对应的安装命令这里给出一个通用示例# GPU 环境示例具体命令以 PyTorch 官网生成器为准 pip install torch torchvision CUDA工具包对应版本 # 如果使用 CPU 环境 pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu接下来安装 transformers、accelerate 以及图像处理相关依赖pip install transformers accelerate pip install pillow pip install sentencepiece pip install pyyaml如果你后面要做 PDF 批量转换还需要安装 PyMuPDF用于把 PDF 页面渲染成图片pip install pymupdf2.4 下载 DeepSeek-OCR 模型权重模型权重的获取方式通常是先到 Hugging Face 或 ModelScope 搜索 DeepSeek-OCR 相关模型库选择合适精度下载到本地。如果 Hugging Face 访问不便可以使用国内镜像export HF_ENDPOINThttps://hf-mirror.com huggingface-cli download 你的模型仓库路径 --local-dir ./models/DeepSeek-OCR这里不写死具体模型仓库路径是因为官方仓库和版本可能更新。建议以你搜索到的最新官方模型页为准。下载完成后目录结构大概如下models/ └── DeepSeek-OCR/ ├── config.json ├── model.safetensors ├── tokenizer.json └── 其他必要文件更稳妥的方式是打开模型主页阅读 README 中的加载代码把代码复制到本地运行。这样能保证加载方式与模型实际结构一致。3. DeepSeek-OCR 基础部署与图片识别3.1 模型加载模型加载是部署的第一步。下面是一个通用的加载代码示例实际使用时请以模型仓库 README 中的加载代码为准import torch from transformers import AutoProcessor, AutoModelForCausalLM model_path ./models/DeepSeek-OCR processor AutoProcessor.from_pretrained(model_path, trust_remote_codeTrue) model AutoModelForCausalLM.from_pretrained( model_path, trust_remote_codeTrue, device_mapcuda:0, torch_dtypetorch.bfloat16 ) model.eval()代码说明AutoProcessor负责把图片处理成模型需要的输入张量。AutoModelForCausalLM加载生成式模型的通用入口。trust_remote_codeTrue允许执行模型仓库自带的远程代码很多新模型没有合入主仓库时都需要开启。torch_dtypetorch.bfloat16使用半精度加载模型减少显存占用。如果你没有 GPU可以把device_map改为cpu并去掉torch_dtype但推理速度会明显下降。3.2 单张图片 OCR 识别接下来实现一个最基础的图片 OCR 函数。from PIL import Image def ocr_image(image_path, model, processor, device, max_new_tokens2048): # 1. 读取图片 image Image.open(image_path).convert(RGB) # 2. 预处理 inputs processor(imagesimage, return_tensorspt).to(device) # 3. 生成 with torch.no_grad(): generate_ids model.generate( **inputs, max_new_tokensmax_new_tokens, do_sampleFalse ) # 4. 解码结果 result processor.batch_decode( generate_ids, skip_special_tokensTrue )[0] return result调用方式也很简单device cuda:0 result ocr_image(test.png, model, processor, device) print(result)这里有几个细节需要注意convert(RGB)可以把 RGBA 或灰度图片统一转成 RGB 格式避免个别图片通道数不一致导致报错。do_sampleFalse表示使用贪心解码。对于 OCR 任务贪心解码的稳定性通常比随机采样更好不容易出现“自由发挥”的文字。max_new_tokens控制生成的最大长度。如果图片文字很多可以调大一些例如 4096。3.3 保存 Markdown 结果识别结果拿到手后直接保存为.md文件即可def save_markdown(result, output_path): with open(output_path, w, encodingutf-8) as f: f.write(result) print(f已保存: {output_path})实际使用中我建议把图片路径和后缀做一个映射避免保存时覆盖同名文件。例如from pathlib import Path image_path Path(test.png) output_path image_path.with_suffix(.md) save_markdown(result, str(output_path))这样test.png会被转换为test.md命名非常直观。4. 批量处理从图片到 Markdown 文档4.1 批量处理需求在实际项目中我们接触的往往不是单张图片而是一个目录下的几十张扫描图片或者一份几百页的 PDF。因此写一个批量处理脚本是必须的。批量处理流程可以拆成三步遍历目录下的图片文件。对每张图片调用 OCR 识别。把识别结果逐页写入 Markdown 文件。4.2 批量处理目录下的图片import os def batch_ocr_image_dir(input_dir, output_dir, model, processor, device): os.makedirs(output_dir, exist_okTrue) supported_ext [.png, .jpg, .jpeg, .bmp, .webp] for file_name in os.listdir(input_dir): ext os.path.splitext(file_name)[1].lower() if ext not in supported_ext: continue image_path os.path.join(input_dir, file_name) output_path os.path.join(output_dir, os.path.splitext(file_name)[0] .md) try: result ocr_image(image_path, model, processor, device) save_markdown(result, output_path) except Exception as e: print(f处理失败: {file_name}, 错误: {e})这里加了一个简单的异常捕获避免单张图片损坏导致整个批次中断。批量任务跑的时间通常较长建议把日志输出到文件方便事后检查。4.3 PDF 批量转 MarkdownPDF 的处理方式与图片不同不能直接把 PDF 喂给 OCR 模型。我们需要先用 PyMuPDF 把 PDF 页面渲染成图片然后再调用 OCR。import fitz def pdf_to_markdown(pdf_path, output_dir, model, processor, device, dpi200): os.makedirs(output_dir, exist_okTrue) doc fitz.open(pdf_path) result_parts [] for page_num, page in enumerate(doc, start1): # 渲染页面为高分辨率图片 pix page.get_pixmap(dpidpi) img_path os.path.join(output_dir, fpage_{page_num}.png) pix.save(img_path) # OCR 识别 text ocr_image(img_path, model, processor, device) # 拼接 markdown 内容 result_parts.append(f## Page {page_num}\n\n{text}) print(f进度: {page_num}/{len(doc)}) # 合并为一个 markdown 文件 output_path os.path.join(output_dir, output.md) with open(output_path, w, encodingutf-8) as f: f.write(\n\n.join(result_parts)) print(fPDF 转换完成: {output_path})dpi 参数决定渲染清晰度。对于文字较小的合同、扫描件建议设置为 200 或 300对于普通电子版 PDF150 通常够用。dpi 越高图片越大OCR 耗时越长。4.4 输出效果与注意事项PDF 转换完成后生成的 Markdown 文件里标题、列表、表格、代码块会尽量保持原有结构。但需要承认OCR 识别不可能 100% 完美尤其是表格线条不清晰时可能出现单元格错位。图片中文字倾斜严重时可能出现漏字。手写文字、艺术字、特殊字体识别效果会下降。所以批量处理后一定要抽样人工校验尤其是用于知识库或对外发布的内容。5. 在 RAG 知识库中使用 DeepSeek-OCR5.1 RAG 的基本流程RAG 全称是 Retrieval-Augmented Generation翻译为“检索增强生成”。它的核心思路是不直接让大模型回答所有问题而是先从知识库中检索出与问题相关的资料片段再把这些片段拼进 Prompt让大模型基于资料内容生成答案。一个基础 RAG 流程包含以下环节文档解析把 PDF、Word、图片等原始文档转换成纯文本或 Markdown。文本分块把长文档切分为适合检索的片段例如 200 到 800 字。向量化用 Embedding 模型把文本片段转换成向量。向量入库把向量和原文存入向量数据库。检索用户提问时把问题向量化在向量库中查询最相似的 TopN 片段。生成把检索到的片段拼入 Prompt再调用大模型生成回答。在这个链路中文档解析是否准确会直接影响后续所有环节的质量。如果文档解析后文本是乱的分块、向量化、召回都不会理想。5.2 把 DeepSeek-OCR 接入文档解析环节DeepSeek-OCR 在 RAG 链路中的定位非常明确它负责文档解析把“无法直接提取文本的 PDF/图片”变成“干净的 Markdown 文档”。接入方式如下扫描版PDF或图片 │ ▼ DeepSeek-OCR 解析输出 Markdown │ ▼ 去除 OCR 噪声标记 │ ▼ 按标题或段落进行文本分块 │ ▼ Embedding 向量化 │ ▼ 写入向量数据库需要注意的是OCR 输出的 Markdown 中可能包含一些对检索没有帮助的噪声例如页眉页脚、重复页码、特殊符号。在分块之前建议做一次清洗。下面是一个简单的清洗函数import re def clean_ocr_markdown(text): # 移除多余的空行 text re.sub(r\n{3,}, \n\n, text) # 移除常见的页眉页脚噪声 lines text.splitlines() clean_lines [] for line in lines: stripped line.strip() if re.match(r^最后更新[:], stripped): continue if re.match(r^第\s*\d\s*页, stripped): continue if re.match(r^\s*$, stripped) and clean_lines and clean_lines[-1] : continue clean_lines.append(line) return \n.join(clean_lines).strip()5.3 向量化与检索问答示例文档处理完成后下一步是向量化和入库。这里以 Chroma 向量数据库和 BGE Embedding 模型为例。先安装依赖pip install chromadb sentence-transformers然后实现向量入库流程import chromadb from chromadb.utils import embedding_functions # 初始化 Embedding 函数 ef embedding_functions.SentenceTransformerEmbeddingFunction( model_nameBAAI/bge-base-zh-v1.5 ) # 创建持久化向量库 client chromadb.PersistentClient(path./chroma_db) collection client.get_or_create_collection( nameocr_knowledge, embedding_functionef ) # 假设这是 DeepSeek-OCR 输出的 Markdown 文档 doc_markdown ## 项目简介 本系统是一个基于 RAG 的智能问答平台核心优势是支持扫描版文档。 ## 技术架构 系统包括 OCR 解析模块、向量检索模块、大模型生成模块。 # 分块按标题/段落切分这里简单演示 chunks doc_markdown.split(\n\n) for i, chunk in enumerate(chunks): if not chunk.strip(): continue collection.add( ids[fdoc_001_chunk_{i}], documents[chunk.strip()], metadatas[{doc_id: doc_001, chunk_index: i}] ) print(向量入库完成)查询时直接调用query方法即可query 系统支持什么样的文档 results collection.query(query_texts[query], n_results2) for doc, distance in zip(results[documents][0], results[distances][0]): print(召回片段:, doc) print(距离:, distance) print(---)召回后把相关片段拼入 Prompt再交给对话大模型生成回答即可。DeepSeek-OCR 负责“看懂文档”Embedding 模型负责“找相关片段”对话大模型负责“组织答案”。三者各司其职链路很清晰。6. LoRA 微调原理与实战思路6.1 为什么选择 LoRA 而非全量微调LoRA 的全称是 Low-Rank Adaptation即低秩适配。它的核心思想是冻结预训练模型的原始参数在模型某些层旁边添加一组低秩的可训练矩阵只更新这组小矩阵从而大幅减少训练参数量。为什么需要 LoRA可以从两个角度理解成本角度全量微调一个大模型需要保存和更新全部参数显存和训练时间都很高。LoRA 只训练新增的小矩阵显存占用大幅下降普通消费级显卡也能尝试。数据角度全量微调在数据量不足时容易过拟合或者破坏预训练模型已经学会的通用能力。LoRA 限制了参数更新的范围模型能在适配新任务的同时保持原有能力。需要说明的是如果训练数据充足、显存足够全量微调可以让模型充分适应新领域效果上限更高。LoRA 并不是“银弹”它的优势在于低成本、快速迭代和灾难性遗忘风险较低。6.2 全量微调、Freeze 微调与 LoRA 微调对比微调方式训练参数显存要求训练速度适用场景全量微调全部参数高慢数据量大、领域差异大Freeze 微调部分层参数中中领域差异较小LoRA 微调低秩矩阵参数低快资源有限、快速迭代Freeze 微调指的是冻结底部若干层只训练靠近输出层的参数可以看作全量微调和 LoRA 之间的折中方案。在实际项目中我的建议是预算允许先用 LoRA 跑一个 baseline。评估效果后如果领域差异确实很大再考虑全量微调。通过验证集指标决定是否值得升级方案而不是从一开始就盲目追求全量微调。6.3 LoRA 微调的核心步骤LoRA 微调的核心流程如下准备领域数据集常见格式是文本对或指令对。使用 Hugging Face Transformers 加载预训练模型。使用 PEFT 库给模型添加 LoRA 适配器。训练。保存 LoRA 权重。在推理时加载原模型 LoRA 适配器。下面是使用 PEFT 添加 LoRA 适配器的代码示例from peft import LoraConfig, get_peft_model, TaskType from transformers import AutoModelForCausalLM, AutoTokenizer model_path 你的预训练模型路径 model AutoModelForCausalLM.from_pretrained( model_path, torch_dtypeauto, device_mapcuda:0 ) tokenizer AutoTokenizer.from_pretrained(model_path) lora_config LoraConfig( task_typeTaskType.CAUSAL_LM, r8, lora_alpha32, lora_dropout0.05, target_modules[q_proj, k_proj, v_proj, o_proj] ) model get_peft_model(model, lora_config) # 查看可训练参数数量 model.print_trainable_parameters()参数说明r低秩矩阵的秩默认 8。数值越小参数量越少数值越大模型表达能力越强也越容易过拟合。lora_alpha缩放参数通常设置为 r 的 2 到 4 倍。lora_dropout防止过拟合的 Dropout 概率。target_modules需要添加 LoRA 适配器的层不同模型结构可能不同。训练完成后保存 LoRA 权重model.save_pretrained(./lora_adapter) tokenizer.save_pretrained(./lora_adapter)推理时加载 LoRA 适配器from peft import PeftModel base_model AutoModelForCausalLM.from_pretrained(model_path) model PeftModel.from_pretrained(base_model, ./lora_adapter)需要提醒的是LoRA 微调虽然参数少但数据处理、评估、防过拟合这些问题一个都不能少。微调不是“跑了就行”而是需要用验证集持续监控效果避免出现重复输出、胡言乱语等问题。7. 常见问题与排查思路7.1 高频问题速查表问题现象常见原因解决思路CUDA out of memory图片过大生成 token 过多调低图片分辨率、减小 max_new_tokens、使用半精度ModuleNotFoundError: torch环境未安装 PyTorch先安装与 CUDA 匹配的 PyTorch再安装其他依赖trust_remote_code 相关报错模型需要运行仓库自定义代码加载时添加 trust_remote_codeTrue并确认来源可信识别结果为空或乱码图片格式不受支持转换图片格式为 PNG/JPEG确认图片不是纯色底中文识别不完整图片清晰度不够提高 PDF 渲染 dpi、对图片做预处理增强长文本被截断max_new_tokens 太小增大 max_new_tokens或对长图分块识别RAG 检索结果差文档解析/分块策略不合理先人工检查 OCR 输出是否干净再调整分块大小LoRA 训练损失不下降数据量太小或学习率不合适增加数据量、调整学习率、检查数据是否重复7.2 强烈建议的排查顺序遇到问题时不要直接改参数盲目重跑按下面顺序排查效率更高先检查环境PyTorch 能否正常使用 GPU、CUDA 版本、显存占用。再检查输入图片路径是否正确图片是否损坏PDF 渲染结果是否清晰。然后检查模型加载是否成功加载权重模型是否处于model.eval()状态。最后检查输出OCR 结果是否被后处理误删Markdown 保存编码是否为 utf-8。8. 工程落地建议与最佳实践8.1 文档质量决定上限DeepSeek-OCR 的识别效果与输入图片质量强相关。在实际工程中同类文档建议统一处理流程扫描图片统一转成 RGB 格式。PDF 渲染固定使用同一 dpi。倾斜严重的图片先做旋转矫正。背景杂乱的图片先做裁剪或去噪。先建立一条“预处理流水线”再接入 OCR 模型整体输出稳定性会高出很多。8.2 数据隐私与安全边界OCR 处理的内容可能是合同、票据、个人证件等敏感信息。在工程落地时有几点必须关注优先本地部署推理避免把敏感文档发送到外部服务。批量处理时对输出 Markdown 做敏感信息脱敏例如手机号、身份证号、银行卡号。如果涉及生产环境变更先在测试环境验证效果再全量执行。模型权重来源要可靠建议从官方渠道下载并校验文件哈希。8.3 算力成本与性能调优OCR 推理属于计算密集型任务在资源有限的情况下可以尝试使用 bf16/fp16 半精度推理减少显存占用。对图片按比例压缩到合理尺寸不需要所有图片都用超高分辨率。使用批量推理而不是逐张 for 循环加载。如果单卡放不下考虑多卡推理或切图处理。同时给 OCR 任务设置超时控制和重试机制避免单张异常图片导致整个任务卡死。8.4 可维护性建议对于长期运行的知识库项目建议用统一命名规范管理文档例如doc_id_页码.md。记录每份文档的 OCR 版本和处理时间。为后续重新处理预留接口模型升级后可以重跑部分文档。定期抽样评估 OCR 输出质量量化错误率而不是“感觉没问题”。9. 总结与学习路线这篇长文从头到尾梳理了 DeepSeek-OCR 的完整实践链路包括DeepSeek-OCR 的核心能力与传统 OCR 的区别。环境准备、模型部署、图片/PDF 批量识别。将 OCR 接入 RAG 知识库的完整流程。LoRA 微调的原理、与全量微调的对比、代码示例。常见问题排查和工程落地建议。如果接下来想继续深入可以按下面的路线学习先跑通 OCR 单图识别熟悉模型加载和参数调节。建立自己的图片/PDF 测试集统计识别准确率。把 OCR 接入一个最小 RAG 项目感受文档解析对检索结果的影响。学习 Embedding 模型选型和分块策略优化知识库召回效果。当领域数据积累到一定规模后再考虑用 LoRA 微调模型进一步适配垂直场景。希望这篇文章能帮你少踩一些坑。如果按步骤操作遇到问题欢迎对照第 7 节的排查表逐项检查也建议先把文章收藏备用后续实践时可以随时查阅。