先把两个项目跑通 → 找到 OCR 后接入 LightRAG 的核心修改点 → 新建分支开发 → 按规范上传分支，我把这个思路拆成「5 个可落地的步骤」，每个步骤告诉你「做什么、改哪里、怎么验证、上传什么」，全程不绕弯，新手也能一步步落地！

---

第一步：先跑通两个项目（基础前提，先排除环境问题）

这一步的目标是：确认「原有代码仓（zoho-ai-server）」和「LightRAG」都能独立运行，避免后续接入时分不清是「代码问题」还是「环境问题」。

1. 跑通原有代码仓（zoho-ai-server）

• 操作：在服务器 / 本地启动项目，测试核心功能 —— 比如上传图片走 OCR 识别，能正常输出文本、能把文本存入数据库（不用管向量，先保证 OCR 链路通）；
• 验证：调用 OCR 接口（或执行 OCR 函数），传入测试图片，能返回识别后的文本 → 证明 OCR 流程没问题；
• 重点：记录 OCR 识别文本后的「核心代码位置」（比如ocr_service.py的ocr_recognize函数，后面要改这里）。

2. 跑通 LightRAG

• 操作：按 LightRAG 的文档安装依赖，执行官方示例代码（比如文本切分、向量化、检索）；
• 验证：运行from lightrag import LightRAG; rag=LightRAG(); print(rag.embed("测试文本"))，能输出向量列表 → 证明 LightRAG 环境没问题；
• 重点：确认 LightRAG 的核心函数（split_text切分文本、embed生成向量、retrieve检索）能正常调用。

✅ 这一步完成后，你就排除了「环境 / 依赖」坑，后续改代码出问题，只聚焦「逻辑适配」即可。

---

第二步：新建分支（隔离开发，不污染原代码）

这一步全程在「原有代码仓」操作，只建分支，不改任何代码，5 分钟搞定：

1. 操作命令（复制即用）

bash

运行

# 1. 进入原有代码仓根目录
cd /你的路径/zoho-ai-server

# 2. 确保主分支代码最新（拉取远程更新）
git pull origin main

# 3. 新建开发分支（命名：feature/ocr-lightrag，明确功能）
git checkout -b feature/ocr-lightrag

# 4. （可选）推送到远程（防止代码丢失）
git push --set-upstream origin feature/ocr-lightrag

2. 关键验证

执行git branch，终端显示*feature/ocr-lightrag → 证明分支创建成功，后续所有修改都在这个分支里做。

---

第三步：核心修改（OCR 识别文本后接入 LightRAG，只改 3 处）

这是最核心的一步，只改 OCR 相关代码，其他代码完全不动，聚焦「OCR 文本→LightRAG 处理→存入向量表」的链路：

1. 找到要改的文件（99% 在这）

原有代码仓中，OCR 识别的核心文件路径（按优先级找）：

plaintext

zoho-ai-server/
├── ocr/services/ocr_service.py  # 优先找！OCR核心服务类
├── document/services/document_service.py  # 文档上传+OCR的逻辑
├── ocr/utils/ocr_utils.py  # OCR工具函数

找到其中包含ocr_recognize（或类似名称）的函数 —— 这个函数是「输入图片→输出文本」的核心，就是你要改的地方。

2. 具体修改逻辑（直接抄，适配你的代码）

python

运行

# 1. 先在文件顶部引入依赖（新增）
from lightrag import LightRAG
from dataset.models.embedding import Embedding  # 你的向量表模型
import uuid  # 生成主键ID用

# 2. 全局初始化LightRAG（新增）
rag = LightRAG()

# 3. 改造你的OCR函数（只在文本提取后加逻辑，原有代码不动）
def ocr_recognize(image_file, dataset_id=None):
    """OCR识别图片，接入LightRAG处理文本"""
    # 原有OCR逻辑（一行不改）
    ocr_result = call_ocr_api(image_file)  # 你的OCR调用逻辑
    text = ocr_result.get("content", "")  # OCR识别出的文本
    
    # ========== 新增：LightRAG处理逻辑 ==========
    if text:  # 只有识别出文本才处理
        # Step1：LightRAG切分文本（按语义切分，比纯换行好）
        text_chunks = rag.split_text(text, chunk_size=512, chunk_overlap=50)
        
        # Step2：遍历文本块，生成向量并存入你的向量表
        for chunk in text_chunks:
            vector = rag.embed(chunk)  # LightRAG生成向量
            # 存入你的Embedding表（适配你的模型字段）
            Embedding.objects.create(
                id=str(uuid.uuid4()),  # 主键ID
                source_id=str(uuid.uuid4()),  # 文本块ID
                source_type="1",  # 段落类型（对应你的SourceType.PARAGRAPH）
                is_active=True,
                dataset_id=dataset_id,  # 关联数据集
                embedding=vector,  # LightRAG生成的向量
                meta={"ocr_text": chunk, "source": "ocr"},  # 标记OCR来源
                search_vector=""  # 保持原有逻辑
            )
    # ========== LightRAG处理结束 ==========
    
    # 原有返回逻辑（一行不改）
    return text

3. 验证修改

执行 Django shell 测试：

bash

运行

python manage.py shell
from ocr.services.ocr_service import ocr_recognize
ocr_recognize("测试图片路径", dataset_id="你的数据集ID")
# 查看向量表是否有数据
from dataset.models.embedding import Embedding
print(Embedding.objects.filter(meta__source="ocr").count())  # 大于0即成功

---

第四步：（可选）嵌入 LightRAG 为子模块（如果需要独立维护 LightRAG）

如果你的 LightRAG 需要单独改代码（比如适配 OCR 文本切分），建议把它作为子模块嵌入原有代码仓；如果只是调用 LightRAG 的默认功能，直接 pip 安装即可，不用嵌子模块。

子模块嵌入操作（在你的开发分支里执行）

bash

运行

# 1. 嵌入LightRAG为子模块（指定存储路径）
git submodule add https://gitee.com/你的账号/LightRAG.git apps/lightrag

# 2. 初始化子模块
git submodule update --init --recursive

# 3. 提交子模块引用（只提交到你的开发分支）
git add .gitmodules apps/lightrag
git commit -m "feat: 嵌入LightRAG子模块"

---

第五步：上传分支（只传修改后的内容，原仓库不动）

这一步的核心是：只上传你的开发分支，原仓库 main 分支完全不变，上传的内容分两种情况：

情况 1：没嵌子模块（直接调用 LightRAG）

上传的内容 = 原有代码仓的开发分支（包含 OCR+LightRAG 的修改）：

bash

运行

# 1. 提交所有修改（在开发分支里）
git add .
git commit -m "feat: OCR识别文本后接入LightRAG，生成向量并存库"

# 2. 推送到远程开发分支（只传这个分支，原main分支不动）
git push origin feature/ocr-lightrag

情况 2：嵌入了 LightRAG 子模块

上传分两步：先传 LightRAG 子模块的修改 → 再传原有代码仓的开发分支：

bash

运行

# 1. 先传LightRAG子模块的修改（如果改了LightRAG代码）
cd apps/lightrag
git add .
git commit -m "fix: 适配OCR文本切分"
git push origin feature/ocr-adapt  # 推到LightRAG自己的仓库

# 2. 回到原有代码仓，传开发分支
cd ../..
git add .
git commit -m "feat: 嵌入LightRAG子模块，OCR后处理文本"
git push origin feature/ocr-lightrag

上传后验证

打开 Gitee 网页：

• 原有代码仓多了feature/ocr-lightrag分支，里面是你改后的代码；
• 原 main 分支代码无任何变化；
• 如果嵌了子模块，LightRAG 仓库多了你的适配分支。

---

核心总结（5 个关键点，一目了然）

1. 先跑通：两个项目独立运行，排除环境坑；
2. 建分支：只在feature/ocr-lightrag分支开发，不碰原代码；
3. 改代码：只改 OCR 函数，在文本提取后加 LightRAG 切分 + 向量化 + 存库逻辑；
4. 嵌子模块（可选）：需要改 LightRAG 代码时才嵌，否则直接 pip 安装即可；
5. 传分支：只传开发分支，原仓库 main 分支不动，子模块需单独传自己的仓库