[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-81675":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":8,"htmlUrl":8,"language":9,"languages":8,"totalLinesOfCode":8,"stars":10,"forks":11,"watchers":10,"openIssues":11,"contributorsCount":11,"subscribersCount":11,"size":11,"stars1d":11,"stars7d":11,"stars30d":11,"stars90d":11,"forks30d":11,"starsTrendScore":11,"compositeScore":12,"rankGlobal":8,"rankLanguage":8,"license":8,"archived":13,"fork":13,"defaultBranch":14,"hasWiki":13,"hasPages":13,"topics":15,"createdAt":8,"pushedAt":8,"updatedAt":16,"readmeContent":17,"aiSummary":18,"trendingCount":11,"starSnapshotCount":11,"syncStatus":19,"lastSyncTime":20,"discoverSource":21},81675,"retrieve-pro-plus","Magic-meet\u002Fretrieve-pro-plus","Magic-meet",null,"Java",31,0,34,false,"main",[],"2026-06-12 04:01:34","# 学术文献智能解析与检索系统\n\n这是一个面向 PDF 学术文献的解析、存储、索引与检索系统。系统支持文献 PDF 上传、源文件存储、GROBID 全文解析、结构化元数据入库、段落级索引、语义向量生成，以及关键词检索、语义检索和混合检索。\n\n本仓库主要提供一套 Docker Compose 部署环境，包含前端、后端、Python 解析\u002F向量服务，以及 MySQL、Kafka、Canal、Elasticsearch、GROBID、FastDFS 等依赖组件。\n\n## 主要功能\n\n- PDF 文献上传、列表查询、详情查询、源文件下载和删除。\n- 基于 FastDFS 保存上传的原始 PDF 文件。\n- 基于 Kafka 将大文件分块投递到异步解析流程。\n- 基于 GROBID 将 PDF 解析为结构化文献 JSON。\n- 基于 MySQL 保存论文、作者、段落、参考文献等结构化数据。\n- 基于 Canal 监听 MySQL binlog，并将论文和段落变更同步到 Kafka。\n- 基于 Elasticsearch 建立论文级和段落级索引，支持 IK 中文分词。\n- 基于 Qwen3 Embedding 生成论文语义向量，支持语义检索。\n- 基于 Spring Boot 提供 REST API 和 gRPC 客户端调用。\n- 基于 Vue 3 + Vuetify 提供浏览器端文献管理与检索页面。\n\n## 系统架构\n\n核心数据流如下：\n\n1. 用户通过前端或 API 上传 PDF。\n2. 后端将源文件写入 FastDFS，同时在 MySQL 中记录上传状态。\n3. 后端将 PDF 按 512 KB 分块发送到 Kafka 的 `pdf` topic。\n4. Python PDF Worker 消费 `pdf` topic，调用 GROBID 解析 PDF，并将解析后的 JSON 发送到 `json` topic。\n5. Spring Boot 消费 `json` topic，将论文、作者、段落、参考文献等数据写入 MySQL。\n6. Canal 监听 MySQL 中 `paper`、`paragraph` 表的 binlog，将变更发送到 Kafka 的 `canal` topic。\n7. Spring Boot 消费 `canal` topic，同步论文和段落文本到 Elasticsearch。\n8. Python Vector Worker 消费 `canal` topic，为论文生成 Qwen3 Embedding，并发送到 `vector` topic。\n9. Spring Boot 消费 `vector` topic，将向量写入 Elasticsearch 的 `paper` 索引。\n10. 检索时，关键词检索走 Elasticsearch 文本索引；语义检索通过 gRPC 调用 Python RPC 服务生成查询向量，再在 Elasticsearch 中进行向量相似度检索；混合检索融合两种结果。\n\n## 技术栈\n\n| 模块     | 技术                                                         |\n| -------- | ------------------------------------------------------------ |\n| 前端     | Vue 3、Vite、Vuetify、Axios、Vue Router、Pinia               |\n| 后端     | Spring Boot 3.2.1、Java 21、Spring Data JPA、Spring Data Elasticsearch、Spring Kafka、gRPC Client |\n| PDF 解析 | Python 3.11、GROBID、grobid2json                             |\n| 向量模型 | Qwen\u002FQwen3-Embedding-0.6B、Transformers、PyTorch CPU         |\n| 数据库   | MySQL 8.0                                                    |\n| 消息队列 | Apache Kafka 3.9.2，KRaft 单节点模式                         |\n| 增量同步 | Canal Server 1.1.8                                           |\n| 搜索引擎 | Elasticsearch 8.19.0 + IK Analyzer                           |\n| 文件存储 | FastDFS + Nginx                                              |\n| 编排     | Docker Compose                                               |\n\n## 目录结构\n\n```text\n.\n├── docker-compose.yml              # 完整部署：中间件 + Python 服务 + Java 后端 + Vue 前端\n├── docker-compose-no.yml           # 不包含 Java 后端和 Vue 前端的部署文件\n├── .env                            # Compose 环境变量\n├── DOCKER_DEPLOY_NOTES.md          # 部署补充说明\n├── mysql\u002F\n│   ├── conf.d\u002F                     # MySQL 配置\n│   └── init\u002F                       # 初始化 SQL\n├── kafka\u002F\n│   └── init\u002Fcreate-topics.sh       # 自动创建 pdf\u002Fjson\u002Fcanal\u002Fvector topic\n├── canal\u002F\n│   └── conf\u002F                       # Canal 配置\n├── elasticsearch\u002F\n│   ├── Dockerfile                  # 构建带 IK Analyzer 的 ES 镜像\n│   └── analysis-ik\u002F                # IK 自定义词典配置\n├── fastdfs\u002F\n│   ├── Dockerfile\n│   └── entrypoint.sh\n└── project\u002F\n    ├── retrieve-java\u002F              # Spring Boot 后端\n    ├── retrieve-python\u002F            # PDF 解析、向量生成、gRPC 服务\n    └── retrieve-vue\u002F               # Vue 前端\n```\n\n## 环境要求\n\n建议使用 Linux 或 macOS 环境运行。Windows 环境建议使用 WSL2。\n\n基础要求：\n\n- Docker Engine 24+。\n- Docker Compose v2。\n- 至少 8 GB 可用内存；如果同时运行 Elasticsearch、GROBID 和 Qwen3 Embedding，建议 16 GB 以上。\n- 首次启动需要下载基础镜像、构建本地镜像并下载 Qwen3 Embedding 模型，网络环境需要能访问 Docker 镜像源、Maven 仓库、npm 仓库和 Hugging Face 或镜像站。\n\nElasticsearch 在 Linux 上通常需要调大 `vm.max_map_count`：\n\n```bash\nsudo sysctl -w vm.max_map_count=262144\n```\n\n如需永久生效，可写入 `\u002Fetc\u002Fsysctl.conf`：\n\n```bash\necho 'vm.max_map_count=262144' | sudo tee -a \u002Fetc\u002Fsysctl.conf\nsudo sysctl -p\n```\n\n## 快速启动\n\n进入项目根目录：\n\n```bash\ncd retrieve_docker\n```\n\n确认关键脚本存在并具有可执行权限：\n\n```bash\nchmod +x kafka\u002Finit\u002Fcreate-topics.sh\nchmod +x fastdfs\u002Fentrypoint.sh\nchmod +x project\u002Fretrieve-python\u002Fdocker\u002F*.sh\n```\n\n首次部署前建议修改 `.env` 中的默认密码、端口和模型缓存路径，尤其是 `MYSQL_ROOT_PASSWORD`、`HF_HOME`、`HF_ENDPOINT` 等变量。不要将包含真实密码的 `.env` 提交到公开仓库。\n\n构建并启动完整系统：\n\n```bash\ndocker compose up -d --build\n```\n\n查看容器状态：\n\n```bash\ndocker compose ps\n```\n\n查看关键日志：\n\n```bash\ndocker compose logs -f qwen3-embedding-init retrieve-python-rpc retrieve-python-pdf retrieve-python-vector retrieve-java retrieve-vue\n```\n\n首次启动时，`qwen3-embedding-init` 会下载默认的 Qwen3 Embedding 模型。模型下载完成后，`retrieve-python-rpc`、`retrieve-python-pdf`、`retrieve-python-vector` 等服务才会继续启动。\n\n## 访问地址\n\n默认端口来自 `.env`：\n\n| 服务                | 地址                    |\n| ------------------- | ----------------------- |\n| 前端页面            | `http:\u002F\u002F127.0.0.1:5173` |\n| 后端 API            | `http:\u002F\u002F127.0.0.1:8080` |\n| Elasticsearch       | `http:\u002F\u002F127.0.0.1:9200` |\n| GROBID API          | `http:\u002F\u002F127.0.0.1:8070` |\n| FastDFS HTTP        | `http:\u002F\u002F127.0.0.1:8888` |\n| Kafka 外部端口      | `127.0.0.1:9092`        |\n| gRPC Embedding 服务 | `127.0.0.1:50051`       |\n\n如果通过局域网或内网穿透访问前端，需要修改：\n\n```text\nproject\u002Fretrieve-vue\u002Fpublic\u002Fapp-config.js\n```\n\n例如：\n\n```js\nwindow.__APP_CONFIG__ = {\n  apiBaseUrl: \"http:\u002F\u002F你的宿主机IP:8080\"\n};\n```\n\n修改后通常不需要重建前端镜像，只需重启前端容器：\n\n```bash\ndocker compose restart retrieve-vue\n```\n\n## API 示例\n\n### 上传 PDF\n\n```bash\ncurl -F \"file=@example.pdf\" \\\n  http:\u002F\u002F127.0.0.1:8080\u002Fapi\u002Fv1\u002Fdocuments\n```\n\n### 查询文献列表\n\n```bash\ncurl http:\u002F\u002F127.0.0.1:8080\u002Fapi\u002Fv1\u002Fdocuments\n```\n\n### 查询单篇文献详情\n\n```bash\ncurl http:\u002F\u002F127.0.0.1:8080\u002Fapi\u002Fv1\u002Fdocuments\u002F1\n```\n\n### 查询文献段落\n\n```bash\ncurl http:\u002F\u002F127.0.0.1:8080\u002Fapi\u002Fv1\u002Fdocuments\u002F1\u002Fchunks\n```\n\n### 下载源文件\n\n```bash\ncurl -OJ http:\u002F\u002F127.0.0.1:8080\u002Fapi\u002Fv1\u002Fdocuments\u002F1\u002Fsource\n```\n\n### 删除文献\n\n```bash\ncurl -X DELETE http:\u002F\u002F127.0.0.1:8080\u002Fapi\u002Fv1\u002Fdocuments\u002F1\n```\n\n### 关键词检索\n\n```bash\ncurl -X POST http:\u002F\u002F127.0.0.1:8080\u002Fapi\u002Fv1\u002Fretrieval\u002Fkeyword \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"query\":\"retrieval augmented generation\",\"topK\":5}'\n```\n\n### 语义检索\n\n```bash\ncurl -X POST http:\u002F\u002F127.0.0.1:8080\u002Fapi\u002Fv1\u002Fretrieval\u002Fsemantic \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"query\":\"efficient document retrieval with embeddings\",\"topK\":5}'\n```\n\n### 混合检索\n\n```bash\ncurl -X POST http:\u002F\u002F127.0.0.1:8080\u002Fapi\u002Fv1\u002Fretrieval\u002Fhybrid \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"query\":\"large language model retrieval system\",\"topK\":5}'\n```\n\n检索请求字段说明：\n\n| 字段         | 类型    | 必填 | 说明                     |\n| ------------ | ------- | ---- | ------------------------ |\n| `query`      | string  | 是   | 检索查询文本             |\n| `topK`       | integer | 否   | 返回结果数量，默认 5     |\n| `documentId` | long    | 否   | 限定在指定上传文献内检索 |\n\n## Kafka Topic\n\n启动时 `kafka-init` 会自动创建以下 topic：\n\n| Topic    | 作用                                               |\n| -------- | -------------------------------------------------- |\n| `pdf`    | 后端上传 PDF 后，将文件分块写入该 topic            |\n| `json`   | Python PDF Worker 将 GROBID 解析结果写入该 topic   |\n| `canal`  | Canal 将 MySQL binlog 变更写入该 topic             |\n| `vector` | Python Vector Worker 将论文 embedding 写入该 topic |\n\n查看 topic：\n\n```bash\ndocker compose exec kafka \u002Fopt\u002Fkafka\u002Fbin\u002Fkafka-topics.sh \\\n  --bootstrap-server kafka:29092 \\\n  --list\n```\n\n## 常用运维命令\n\n查看所有服务状态：\n\n```bash\ndocker compose ps\n```\n\n查看某个服务日志：\n\n```bash\ndocker compose logs -f retrieve-java\n```\n\n重启某个服务：\n\n```bash\ndocker compose restart retrieve-java\n```\n\n停止全部服务：\n\n```bash\ndocker compose down\n```\n\n停止并删除本地构建镜像：\n\n```bash\ndocker compose down --rmi local\n```\n\n清理持久化数据需要谨慎操作。以下目录包含运行时数据，删除后数据不可恢复：\n\n```text\nmysql\u002Fdata\u002F\nkafka\u002Fdata\u002F\nelasticsearch\u002Fdata\u002F\nfastdfs\u002Fdata\u002F\ncanal\u002Flogs\u002F\nhuggingface\u002F\n```\n\n## 分模块开发\n\n### 后端 retrieve-java\n\n后端位于：\n\n```text\nproject\u002Fretrieve-java\n```\n\n主要配置文件：\n\n```text\nproject\u002Fretrieve-java\u002Fsrc\u002Fmain\u002Fresources\u002Fapplication.yml\n```\n\n主要接口入口：\n\n```text\nproject\u002Fretrieve-java\u002Fsrc\u002Fmain\u002Fjava\u002Fedu\u002Fnjucm\u002Fretrievejava\u002Fcontroller\u002FDocumentController.java\n```\n\n如需本地运行，需要提前启动 MySQL、Kafka、Elasticsearch、FastDFS 和 Python gRPC 服务，并配置对应环境变量。Docker 环境下由 `docker-compose.yml` 自动注入这些变量。\n\n### Python 服务 retrieve-python\n\nPython 模块位于：\n\n```text\nproject\u002Fretrieve-python\n```\n\n包含三类运行入口：\n\n| 服务                     | 启动脚本                        | 作用                                |\n| ------------------------ | ------------------------------- | ----------------------------------- |\n| `retrieve-python-rpc`    | `docker\u002Fstart-rpc.sh`           | 提供 gRPC 查询向量生成服务          |\n| `retrieve-python-pdf`    | `docker\u002Fstart-pdf-worker.sh`    | 消费 PDF 分块，调用 GROBID 解析     |\n| `retrieve-python-vector` | `docker\u002Fstart-vector-worker.sh` | 消费 Canal 变更，生成论文 embedding |\n\n默认模型为：\n\n```text\nQwen\u002FQwen3-Embedding-0.6B\n```\n\n如果要替换 embedding 模型，需要同时确认以下内容：\n\n1. `.env` 中的 `QWEN3_EMBEDDING_MODEL`。\n2. `project\u002Fretrieve-python\u002Fdocker\u002Fdownload_qwen3_embedding.py` 中初始化下载的模型名。\n3. Elasticsearch 中 `PaperES.embedding` 的向量维度配置。当前代码中维度为 `1024`。\n\n### 前端 retrieve-vue\n\n前端位于：\n\n```text\nproject\u002Fretrieve-vue\n```\n\n本地开发：\n\n```bash\ncd project\u002Fretrieve-vue\nnpm install\nnpm run dev\n```\n\n生产构建：\n\n```bash\nnpm run build-only\n```\n\n前端 API 地址由以下文件控制：\n\n```text\nproject\u002Fretrieve-vue\u002Fpublic\u002Fapp-config.js\n```\n\n## 常见问题\n\n### 1. Elasticsearch 启动失败\n\n先检查宿主机参数：\n\n```bash\nsudo sysctl -w vm.max_map_count=262144\n```\n\n再检查数据目录权限。如果 `elasticsearch\u002Fdata` 是从其他机器拷贝过来的，可能存在权限问题。可以在确认不需要旧数据后清空该目录，或者调整目录权限。\n\n### 2. Kafka topic 没有创建\n\n检查初始化脚本是否存在且不是目录：\n\n```bash\nls -l kafka\u002Finit\u002Fcreate-topics.sh\n```\n\n如果该路径被误创建成目录，需要删除目录并恢复脚本文件。正常情况下 `kafka-init` 容器会在 Kafka 健康后自动创建 `pdf`、`json`、`canal`、`vector` 四个 topic。\n\n### 3. 前端能打开，但请求仍然访问 `127.0.0.1:8080`\n\n修改：\n\n```text\nproject\u002Fretrieve-vue\u002Fpublic\u002Fapp-config.js\n```\n\n将 `apiBaseUrl` 改为浏览器实际可访问的后端地址。例如局域网访问时应使用宿主机局域网 IP，而不是容器名或 `127.0.0.1`。\n\n修改后重启前端容器：\n\n```bash\ndocker compose restart retrieve-vue\n```\n\n### 4. 上传后长时间处于解析中\n\n按顺序检查：\n\n```bash\ndocker compose logs -f retrieve-java\ndocker compose logs -f retrieve-python-pdf\ndocker compose logs -f grobid\ndocker compose logs -f kafka\n```\n\n重点确认：\n\n- `pdf` topic 是否收到文件分块。\n- `retrieve-python-pdf` 是否成功连接 GROBID。\n- GROBID 是否健康。\n- `json` topic 是否有解析结果。\n- Spring Boot 是否成功消费 `json` topic 并写入 MySQL。\n\n### 5. 语义检索无结果或 embedding 为空\n\n检查：\n\n```bash\ndocker compose logs -f qwen3-embedding-init retrieve-python-rpc retrieve-python-vector retrieve-java\n```\n\n重点确认：\n\n- 模型是否下载完成。\n- `retrieve-python-rpc` 是否启动成功。\n- `retrieve-python-vector` 是否消费到 `canal` topic。\n- `vector` topic 是否有消息。\n- Elasticsearch `paper` 索引中的 `embedding` 字段是否已写入。\n\n### 6. FastDFS 无法下载源文件\n\n检查 FastDFS 服务：\n\n```bash\ndocker compose logs -f fastdfs\n```\n\n并确认后端环境变量中 Tracker 地址为：\n\n```text\nFASTDFS_TRACKER_SERVERS=fastdfs:22122\n```\n\n在 Docker Compose 网络内，应使用服务名 `fastdfs`，不要使用 `127.0.0.1`。\n\n## 部署注意事项\n\n- 当前 Compose 更适合单机开发、实验和课程项目部署，不建议直接作为生产环境配置。\n- `.env` 中的密码和端口应按实际环境修改。\n- Elasticsearch 关闭了 xpack security，默认不启用认证；公网部署时必须放在内网或增加网关鉴权。\n- MySQL、Kafka、Elasticsearch、FastDFS 的数据目录是持久化目录，迁移或清理前应先备份。\n- `docker-compose-no.yml` 只启动中间件和 Python 相关服务，不包含 Java 后端和 Vue 前端，适合只调试基础设施或单独在宿主机运行后端\u002F前端。\n\n## 许可证\n\n当前仓库未声明许可证。如需公开发布，建议补充 `LICENSE` 文件并明确第三方依赖、模型和数据的使用约束。\n","这是一个面向PDF学术文献的解析、存储、索引与检索系统。项目的核心功能包括文献上传、全文解析、结构化数据存储以及多维度检索。技术特点方面，使用了GROBID进行全文解析，MySQL存储结构化数据，Elasticsearch支持高效检索，Qwen3 Embedding生成语义向量，并通过Kafka实现异步处理流程。此外，项目还提供了基于Spring Boot的REST API和gRPC客户端调用，以及一个Vue 3构建的前端界面。该系统适合需要对大量学术文献进行管理和检索的研究机构或个人使用。",2,"2026-06-11 04:05:56","CREATED_QUERY"]