Skip to content

Makefile RAG 更新

Makefile 已更新以支持增强的 RAG Worker 能力，基于改进的双语向量处理系统。此次更新包括新增目标、改进的错误处理、环境校验和更完善的帮助文档。

新增 RAG 目标

1. 增强现有目标

rag-upload（已更新）

  • 新增：环境变量校验（ADMIN_TOKEN、WORKER_URL）
  • 新增：更友好的错误提示及示例
  • 新增：处理前文件校验
  • 用法：make rag-upload FILE=content/zh/blog/my-post/index.md

rag-upload-dir（已更新）

  • 新增：输出中显示草稿文件过滤信息
  • 新增：环境变量校验
  • 新增：更详细的进度报告
  • 用法：make rag-upload-dir DIR=content/zh/book

2. 新增 RAG 目标

rag-upload-batch

  • 用途：一次上传多个目录
  • 特性：支持空格分隔的目录列表
  • 用法：make rag-upload-batch DIRS='content/zh/book content/en/docs'
  • 优势：高效处理双语内容

rag-fast-ingest

  • 用途：高速并行处理所有内容
  • 特性：针对大规模导入进行最大并发优化
  • 用法：make rag-fast-ingest
  • 优势：最快重建整个向量数据库

rag-upload-config

  • 用途：上传外部配置到 Cloudflare R2
  • 特性：自动生成并上传双语标题字典
  • 用法：make rag-upload-config
  • 优势：实现零停机配置更新

rag-test

  • 用途：全面测试 RAG 系统
  • 特性：组件及端到端功能测试
  • 用法：make rag-test
  • 优势：验证系统健康与性能

rag-verify

  • 用途：校验向量数据完整性
  • 特性：检查数据导入逻辑与一致性
  • 用法：make rag-verify
  • 优势：确保数据质量与完整性

rag-reindex

  • 用途：重建整个向量数据库
  • 特性：交互式确认，完整数据替换
  • 用法：make rag-reindex
  • 优势：故障排查与优化的干净起点

rag-deploy（增强）

  • 新增：部署前自动构建
  • 新增：集成外部配置上传
  • 新增：部署状态报告
  • 用法：make rag-deploy

增强帮助文档

新增 RAG 示例部分

RAG 系统示例:
  make rag-upload FILE=content/zh/blog/my-article/index.md # 上传指定文件到 RAG 系统
  make rag-upload-dir DIR=content/zh/book              # 递归上传目录下所有 index.md 文件
  make rag-upload-batch DIRS='content/zh/book content/en/docs' # 批量上传多个目录
  make rag-upload-config                          # 上传外部配置到 Cloudflare R2
  make rag-test                                   # 测试 RAG 系统组件
  make rag-verify                                 # 验证向量数据完整性
  make rag-reindex                                # 重新索引所有向量数据

新增环境变量说明

RAG 环境变量设置:
  export ADMIN_TOKEN=your-cloudflare-token          # Cloudflare 访问令牌
  export WORKER_URL=https://your-worker.workers.dev  # Worker URL
  export PROVIDER=qwen                              # 嵌入提供商 (qwen/gemini)
  export QWEN_API_KEY=your-qwen-key                  # 通义千问 API 密钥

主要改进点

1. 双语内容支持

  • 所有目标自动处理中英文内容
  • 不同语言路径自动 URL 映射
  • 草稿文件过滤，支持 cascade 继承

2. 环境校验

  • 执行前检查所需环境变量
  • 错误提示清晰，附设置说明
  • 校验 Node.js 及其他依赖

3. 错误处理

  • 全面输入校验
  • 文件与目录存在性检查
  • 失败时友好提示

4. 文档增强

  • 每个目标均有清晰用法示例
  • 环境设置说明
  • 部署信息展示

5. 外部配置管理

  • 支持基于 R2 的配置存储
  • 自动生成并上传标题字典
  • 零停机配置更新

工作流示例

初始化设置

# 设置环境变量
export ADMIN_TOKEN=your-cloudflare-token
export WORKER_URL=https://website-rag-worker.jimmysong.io
export PROVIDER=qwen
export QWEN_API_KEY=your-qwen-key

# 部署 RAG Worker
make rag-deploy

内容上传工作流

# 单文件上传
make rag-upload FILE=content/zh/blog/new-post/index.md

# 目录上传
make rag-upload-dir DIR=content/zh/book/kubernetes-handbook

# 双语批量上传
make rag-upload-batch DIRS='content/zh/book content/en/docs'

# 快速批量导入
make rag-fast-ingest

维护操作

# 测试系统健康
make rag-test

# 校验数据完整性
make rag-verify

# 更新外部配置
make rag-upload-config

# 全量重建索引（需确认）
make rag-reindex

技术优势

  1. 简化开发流程：复杂操作一条命令搞定
  2. 双语处理：自动支持中英文内容
  3. 生产级保障：环境校验与错误处理
  4. 可扩展架构：支持外部配置管理
  5. 易维护系统：全面测试与校验工具

兼容性

  • 现有脚本：所有 npm run 命令依然可用
  • 环境变量：采用标准 RAG worker 环境设置
  • Hugo 集成：遵循 Hugo 草稿设置与内容结构
  • Cloudflare 集成：兼容 Workers 与 R2 服务

新版 Makefile 为双语 RAG 向量操作提供了完整工具集，兼顾日常开发的简洁与可靠性。