岩石文甲骨文资料整理：本地OCR、多模态批注与向量检索工作流

最近整理“兰玉献岩石文甲骨文”相关的数字资料时，我一直在想一个问题：这些岩石文、甲骨文影像和释读笔记，到底应该怎么组织，才能让后续研究真正提速？很多人以为这类工作只要装一个 OCR 就能自动识别，实际情况远没那么简单。影像来源混杂、光线和刻痕差异大、释读意见分散在不同文档里，真正缺的不是“认识甲骨文”的模型，而是一条能跑通的本地整理流水线。

这篇文章不展开历史结论，不讨论古代经济治理的具体制度评价，只做技术层面的拆解：以“兰玉献岩石文甲骨文”这类素材为例，演示一套覆盖影像预处理、OCR 区域检测、多模态模型辅助描述、人工批注回填、向量检索、批量任务和接口服务的本地工作流。环境以 Python 为主，GPU 可加速但不是必需，最终产物是一份可追溯、可检索、可导出的结构化资料库。

涉及“华夏老祖先如何治理经济”这种题目时，传统做法往往是用纸笔摘录文献，再按制度类别做卡片，效率低、版本容易混。本文给出的方案是把这项工作拆成“影像归档—机器初读—人工复核—检索导出”四个环节，把技术工具嵌到每一步，让研究者把时间花在判断和释读上，而不是花在找图、对版本、抄文字上。

1. 核心能力速览

为了避免把方案讲成概念，先把这套整理工作流的核心能力列出来。它不是一个单一开源项目，而是由多个可替换组件组成的本地流水线，涉及 OCR、多模态视觉模型、向量数据库和 FastAPI 接口服务。

这里的“OCR”对甲骨文和岩石文并没有神奇效果。通用 OCR 更适合检测文字区域、表格化字符块，而不是直接输出可靠释文。真实场景中，机器负责把影像变成可检索的元数据和草稿文本，人工再从草稿中挑有效信息。只有把预期放低，工具才不会反过来添乱。

2. 适用场景与使用边界

这套工作流适合谁？第一类是手里攒了几百张岩石文、甲骨文照片但缺统一目录的研究者，第二类是需要对碑刻拓片做批量归类的资料员，第三类是打算把考古影像接入多模态模型做辅助判读的技术爱好者。共同点是素材量大、命名不统一、备注分散在 Word、Excel 和聊天记录里。

它能解决的实际问题有三个。一是影像防丢失和去重，通过文件哈希和目录分层管理原始图片；二是把机器初读结果和人工释读意见集中在同一张表格里，避免“图片一处、笔记一处、引用又一处”；三是把结构化数据接进向量检索，用自然语言快速找到“某批祭祀刻辞”或“某类农作物记录”，而不是一页页翻 PDF。

使用边界也要说清楚。通用 OCR 不能识别甲骨文本身，如果强行用结果当作释文会闹笑话。多模态模型输出描述性文字，只能作为线索，不能作为学术定论。涉及“华夏祖先如何治理经济”这类需要考据原始文献的大题目，本文只解决材料的归档、检索和版本追溯，不替代历史学论证。所有解释都必须回到权威出版物、馆藏编号和专家释文。

合规方面同样要重视。岩石文、甲骨文、碑刻的影像通常涉及文物保护、馆藏机构版权和个人拍摄授权。本地整理时不代表可以随意公开传播；商用、出书、发表论文时务必确认来源馆藏和版权许可。如果涉及未公开出土材料，还要遵循考古信息发布的相关管理规定。文章的底线是：技术可以做“正本清源”的整理工具，但不能成为绕过授权、滥用影像资料的通道。

3. 环境准备与前置条件

建议在 Windows 11 或 Ubuntu 22.04 上运行。基础流程只需要 Python 3.10 和 pip，不需要显卡也能跑通影像预处理和轻量 OCR。若需要部署本地多模态视觉模型，再准备 CUDA 环境，安装对应版本的 PyTorch。

开始前先建目录，这是整个流程的地基。建议按下述结构管理：

data/ raw/ # 原始照片，只读，不修改 processed/ # 预处理增强后的图像 ocr_output/ # OCR 检测结果 JSON/CSV manual_notes/ # 人工批注文件 export/ # 最终导出报告 scripts/ preprocess.py ocr_detect.py caption_model.py search_service.py logs/

这种分层的最大好处是原始素材不被误覆盖，后续模型升级或参数调整时不用重新拷图片。processing 目录里放的是可再生成的中间产物，即使删掉也能从 raw 重跑。

然后创建 Python 虚拟环境并安装依赖。给出一个最小依赖文件：

mkdir venv python -m venv venv # Windows venv\Scripts\activate # Linux/macOS source venv/bin/activate

opencv-python paddleocr # 按实际项目版本安装，不锁定具体版本 paddlepaddle # CPU 版即可跑基础流程 fastapi uvicorn pillow pandas chromadb requests

安装命令：

pip install -r requirements.txt

如果本机没有 NVIDIA 显卡或不想装 CUDA，PaddleOCR 的 CPU 推理也能用，只是每张图耗时会长一些。多模态模型部分可以用远程兼容接口替代本地模型，这样显存压力就会转移到服务端。

4. 安装部署与启动方式

先写一个预处理脚本，把 raw 目录里的图像统一成可处理的格式，并做一次归一化增强。代码以本机路径为准，实际使用时替换路径：

import os import cv2 from pathlib import Path RAW_DIR = Path("./data/raw") PROCESSED_DIR = Path("./data/processed") PROCESSED_DIR.mkdir(parents=True, exist_ok=True) def preprocess_image(img_path, out_path): img = cv2.imread(str(img_path)) if img is None: return False gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY) # CLAHE 局部对比度增强，适合刻痕较浅的岩石文照片 clahe = cv2.createCLAHE(clipLimit=2.0, tileGridSize=(8, 8)) enhanced = clahe.apply(gray) cv2.imwrite(str(out_path), enhanced) return True for img_path in sorted(RAW_DIR.iterdir()): if img_path.suffix.lower() not in [".jpg", ".jpeg", ".png", ".tif", ".tiff"]: continue out_path = PROCESSED_DIR / img_path.name ok = preprocess_image(img_path, out_path) print(img_path.name, "OK" if ok else "FAILED")

这个脚本先跑一遍，确认 processed 目录里出现了对应的增强图，再继续后面的步骤。

OCR 检测部分采用 PaddleOCR。这里只用于检测文字区域并返回坐标，不直接当作甲骨文释文。调用示例：

from paddleocr import PaddleOCR # 新版 PaddleOCR 的初始化参数可能略有不同，以环境中的版本为准 ocr = PaddleOCR(use_angle_cls=True, lang="ch", show_log=False) result = ocr.ocr("./data/processed/example.jpg", cls=True) for line in result[0]: # line[0] 是文本框坐标，line[1][0] 是识别文本，line[1][1] 是置信度 print(line[0], line[1][0], line[1][1])

如果识别结果为空，不要急着调参。甲骨文、岩石文刻痕会让通用模型输出乱码或空列表，这是正常现象。真正有用的输出是“文本框坐标”，它可以帮助把图片分区，后续按区域做人工注记和裁剪对比。

接口服务用 FastAPI 包一层。这样做的价值在于：研究者不用打开终端，浏览器调用接口就能提交图片、查进度、导出结果。核心示例：

from fastapi import FastAPI from pydantic import BaseModel import subprocess app = FastAPI() class ProcessRequest(BaseModel): img_path: str task_type: str = "preprocess" @app.post("/process_image") def process_image(req: ProcessRequest): # 实际项目这里应校验路径，避免越权和非法文件 cmd = ["python", "preprocess.py", "--img", req.img_path] subprocess.run(cmd, check=True) return {"status": "done", "img_path": req.img_path} @app.get("/health") def health(): return {"status": "alive"} if __name__ == "__main__": import uvicorn uvicorn.run(app, host="127.0.0.1", port=8000)

启动命令：

python app.py # 终端显示 Uvicorn running on http://127.0.0.1:8000 后，访问该地址确认服务正常

先启动服务，再上传一张测试图，确认返回结构正常。接口能跑通，后面就可以把前端页面、Excel 批注表、批量任务脚本全部接到这个服务上。

5. 功能测试与效果验证

5.1 影像预处理测试

测试目的是确认 CLAHE 增强对刻痕和纸面干扰有效果。输入一张光照不均的岩石文照片，输出灰度增强图；判断标准是肉眼可见的轮廓对比度变化，尤其是在刻痕区域。如果增强后噪点被放大，说明 clipLimit 偏高，往 1.0 到 1.5 调低。如果照片本身清晰，也可以直接跳过增强，把原图交给下一步。

5.2 OCR 区域检测测试

测试目的是验证通用 OCR 能否把图片中的文字/刻痕区域切成有意义的分块。输入同一张增强图，观察返回的文本框是否覆盖文字行。对甲骨文，识别文本可能是乱码或空白，只要坐标合理就表示检测成功。判断标准是“坐标框覆盖到了可见内容”，而不是“识别出正确释文”。

失败时优先看两块：一是图像尺寸过大，建议将长边缩放到 2000 像素左右再跑；二是背景干扰太强，先做二值化或去背景。处理后的图片保存为 PNG，避免 JPEG 压缩带来的边缘噪声。

5.3 多模态模型辅助描述测试

很多本地部署的多模态模型都提供 OpenAI 兼容接口。测试时用一张拓片照片，请求模型生成简洁的画面描述，输出包括图中元素、排列方式、大致内容主题。代码示例：

from openai import OpenAI client = OpenAI( base_url="http://127.0.0.1:8000/v1", # 替换为实际模型服务地址 api_key="EMPTY" ) resp = client.chat.completions.create( model="local-vl-model", messages=[ { "role": "user", "content": [ {"type": "text", "text": "请用中文描述这张图中的可见内容，不要直接给出释文，不要编造缺字补字。"}, {"type": "image_url", "image_url": {"url": "file:///data/processed/example.png"}} ] } ] ) print(resp.choices[0].message.content)

判断标准：输出是否基于图片可见内容，是否避免过度推断，是否明确标注不确定处。如果模型给出清晰的学术判断，必须人工复核后再写入资料库。这一步的目的是给研究者提供线索，不是替代研究。

5.4 人工批注回填测试

机器输出只是半成品，最终资料库需要人工批注表。建议用 CSV 保存，字段如下：

回填完成后，所有资料就有了统一的“机器初读 + 人工复核”双层记录。后续引用、比对、做索引都从这个表出发，而不是继续散落在多个 Word 文档里。

5.5 向量检索小实验

资料库批注超过一定量级，用关键词匹配就会漏。用 ChromaDB 把 human_notes 转成向量，做语义检索：

import chromadb from chromadb.utils import embedding_functions client = chromadb.PersistentClient(path="./data/chroma_db") col = client.get_or_create_collection("notes") col.add( ids=["1", "2"], documents=["关于祭祀用牲的刻辞记录", "与农业生产及谷物征收相关的材料"], metadatas=[{"file": "YS_001.png"}, {"file": "YS_002.png"}] ) results = col.query(query_texts=["古代农业经济相关记录"], n_results=2) print(results["documents"])

这样做的意义很实际：研究者可以直接问“这批资料里有哪些涉及经济活动的材料”，而不是把所有释读笔记重新读一遍。向量检索跑通后，再扩大资料量就只是增量写入问题。

6. 接口 API 与批量任务

整理工作流如果没有批量任务，每次传一张图效率太低。把批量处理做成一个独立脚本，循环遍历输入目录，输出结构化 CSV，并在日志中记录成功或失败状态。

python batch_process.py --input_dir ./data/raw --output_dir ./data/export --log_dir ./logs

批量脚本内部核心逻辑：

import csv import time from pathlib import Path def process_one(file_path): # 调用预处理、OCR 检测、多模态描述 return {"file_name": file_path.name, "status": "ok"} results = [] log_rows = [] input_dir = Path("./data/raw") export_dir = Path("./data/export") for file_path in sorted(input_dir.iterdir()): try: row = process_one(file_path) results.append(row) log_rows.append({"ts": time.time(), "file": file_path.name, "status": "ok"}) except Exception as exc: log_rows.append({"ts": time.time(), "file": file_path.name, "status": "failed", "error": str(exc)}) with open(export_dir / "results.csv", "w", newline="", encoding="utf-8") as f: writer = csv.DictWriter(f, fieldnames=["file_name", "status"]) writer.writeheader() writer.writerows(results) with open(export_dir / "batch_log.csv", "w", newline="", encoding="utf-8") as f: writer = csv.DictWriter(f, fieldnames=["ts", "file", "status", "error"]) writer.writeheader() writer.writerows(log_rows)

批量任务必须加日志和失败重试。一张模糊图片可能导致 OCR 进程吞掉大量内存，建议为每张图设置超时，失败后跳过并记录，而不是让整个任务卡死。

API 侧至少暴露三个接口：

批量任务不要在同一请求里同步跑完，更稳妥的方式是先创建任务 ID，由后台进程消费队列，前端轮询进度。涉及大量图片时要限制服务访问范围，只在局域网或本机开放，避免被外部滥用。接口层对传入的 img_path 要做路径校验，不能允许任意文件读取。

7. 资源占用与性能观察

如果按常见本地部署流程测试，可以重点观察三块：CPU/GPU 占用、内存占用、单张图片处理耗时。纯 CPU 跑 PaddleOCR 时，每张 2000 像素的图片大约需要几秒到十几秒，具体取决于 CPU 代数、并发线程数和图像复杂度。有 NVIDIA 显卡时，OCR 和本地多模态模型都能利用 CUDA 加速，但显存占用需要以实际模型版本和推理参数为准，不同精度、不同分辨率差异很大。

观察显存最直接的方法是另开一个终端运行：

nvidia-smi -l 1

日志中可以看到显卡占用和进程 PID。如果显存接近满载，优先降低多模态模型的输入分辨率，或改用 4bit 量化版模型。纯 CPU 环境则打开任务管理器或 htop 观察内存占用，PaddleOCR 在并发处理时可能消耗较多内存，出现内存溢出时不要一次跑整个目录，改用一次处理三到五张的小批次。

影响性能的参数主要有四类：输入图像分辨率、OCR 推理的 batch 大小、线程池并发数、多模态模型规模。分辨率越高，预处理和 OCR 耗时越长；纹理复杂的大图可以先缩到长边 2000 像素再处理。批量任务不要盲目开高并发，先跑五张图估算单张耗时，再按“剩余张数 * 单张耗时”判断总时长，避免服务被压垮。

降低资源占用的通用做法：关闭不需要的模型进程、限制并发数量、把日志从 DEBUG 调到 INFO、定期清理 processed 和 export 中的中间文件。端口冲突时检查占用进程：

netstat -ano | findstr :8000 taskkill /PID 对应PID /F

换端口启动也很简单：把 uvicorn 的 port 改成 8001 或 8010。为了避免下次启动时端口被残留进程占用，服务结束前最好写一个关闭脚本，杀掉当前启动的 PID。

8. 常见问题与排查方法

遇到依赖安装失败时，优先用国内镜像源重新安装：

pip install paddleocr -i https://pypi.tuna.tsinghua.edu.cn/simple

如果 CUDA 版本对不上，不要盲目升级驱动，先执行nvidia-smi查看驱动支持的 CUDA 版本，再安装对应版本的 PyTorch。环境变量和路径以实际配置为准。

9. 最佳实践与使用建议

这套工作流要真正用起来，不能只装依赖跑脚本，工程化要有意识。第一次建议只拿 20 张图做全流程验证，而不是直接把几千张图丢进批量任务。先小规模跑通，确认目录结构、字段设计和接口返回都没问题，再扩展到全量数据。

原始素材管理要“只读优先”。raw 目录只存放原始拍摄文件，文件名建议按“来源单位_编号_拍摄日期”的规则重命名，并额外存一个 file_hash 字段，防止重复拷贝后无法识别。processed、ocr_output、export 都属于可再生成目录，即使误删也能从 raw 重新跑。每一次批量任务都写日志，日志包含文件路径、处理时间、状态和异常信息，这样哪张图失败一眼就能看到。

多模态模型的辅助描述必须加“人工复核”环节。任何由模型生成的文字都不应直接作为释文引用，也不应直接进入正式研究笔记。稳妥的做法是让模型输出进入待审核队列，由研究人员确认后转存到 manual_notes。对准确性要求较高的场景，建议在提示词中明确要求模型标注不确定信息，不补字、不推测。

接口服务要控制访问范围。开放给局域网内部使用时，监听地址可以设为127.0.0.1或内网 IP，不要直接暴露到公网。传入文件路径时必须做白名单校验，防止有人通过路径穿越读取服务器上的任意文件。导出目录和原始目录分开，防止接口异常时污染原始素材。

版权合规是整理工作中最容易被忽略的一环。岩石文、甲骨文、碑刻拓片的照片往往不是“谁拍的谁就有全部版权”，馆藏机构、出土报告、数据库平台都可能主张权利。无论做研究还是做商业内容，务必确认图片来源、授权范围和使用限制。涉及人脸、声音、私密资料的素材，同样要获得合法授权后才能使用。对不确定权属的材料，宁可先标记为“待授权”，也不要直接发布。

10. 总结与下一步

这套“兰玉献岩石文甲骨文”资料整理工作流的价值不在某个单一模型，而在于把分散环节串成一条可执行、可追溯、可批量扩大的本地流水线。最值得先验证的功能是影像预处理和 OCR 区域检测，因为这两步决定了后续所有环节能不能拿到稳定输入。最容易踩的坑是让通用 OCR 直接输出甲骨文释文，正确的用法是把它当作分区工具，释读交给人工和多模态模型复核。第一次启动不要追求全量跑完，先把 20 张图的处理链路打通，再逐步增加数据。

后续可以继续扩展的方向不少：接一个专门训练的文字识别模型来做甲骨文刻痕分类，接入支持角色统一性的多模态模型做更稳定的图像注记，或者把人工批注表转成标准文献数据库格式，方便论文引用和版本对照。接口层已经预留了/process_image、/batch_process、/export/report三个入口，很多工具可以直接通过 HTTP 接进来。这批资料数字化完成之后，再谈“文化正本清源”就有一个扎实的底座：每一张图都有编号、每一次机器初读都有记录、每一条释读意见都能追溯到人、版本和时间。