快速入门

本指南将帮助你在 5 分钟内完成 Knowledge 服务的部署与使用。

前置条件

必需组件

组件	版本要求	说明
JDK	21+	Spring Boot 运行环境
PostgreSQL	14+	需安装 `pgvector` 扩展
MySQL	8.0+	元数据、会话管理
Embedding API	OpenAI 兼容	如 Ollama、通义千问、DeepSeek
Chat API	OpenAI 兼容	如 GPT-4、通义千问、DeepSeek

可选组件

组件	说明
Elasticsearch	关键词检索 (低配服务器可用 Lucene 替代)
DashScope API	重排序服务 (qwen3-rerank)
文档转换服务	MarkItDown、LibreOffice、MinerU (独立部署)

第一步: 初始化数据库

PostgreSQL 配置

sql

-- 创建数据库
CREATE DATABASE knowledge;

-- 启用 pgvector 扩展
\c knowledge;
CREATE EXTENSION vector;

MySQL 配置

sql

-- 创建数据库
CREATE DATABASE knowledge DEFAULT CHARACTER SET utf8mb4;

执行 Knowledge 服务的数据库迁移脚本 (MyBatis-Plus 会自动建表,或手动执行 SQL 脚本)。

第二步: 配置应用

创建 application.yml 配置文件:

yaml

spring:
  # ==================== 数据源 ====================
  datasource:
    url: jdbc:mysql://localhost:3306/knowledge?useUnicode=true&characterEncoding=utf-8
    username: root
    password: ${MYSQL_PASSWORD}
  
  # ==================== 向量数据库 ====================
  ai:
    vectorstore:
      pgvector:
        dimensions: 1536
        index-type: HNSW
        distance-type: COSINE_DISTANCE
        initialize-schema: true
    
    # ==================== Embedding 模型 ====================
    openai:
      base-url: https://api.openai.com  # 或其他兼容接口
      api-key: ${OPENAI_API_KEY}
      embedding:
        options:
          model: text-embedding-3-small  # 或其他 embedding 模型

      # ==================== Chat 模型 ====================
      chat:
        options:
          model: gpt-4o  # 或其他 chat 模型
          temperature: 0.7

# ==================== Knowledge 配置 ====================
molandev:
  rag:
    # 分片配置
    splitting:
      chunk-size: 1000
      overlap-size: 200
    
    # 检索配置
    retrieval:
      top-k: 20
      threshold: 0.4
    
    # 文档转换服务 (可选)
    converter:
      mark-it-down-url: http://localhost:10996
      libre-office-url: http://localhost:10997
      mineru-url: http://localhost:10998

第三步: 启动服务

bash

# 编译项目
mvn clean package -DskipTests

# 启动服务
java -jar molandev-knowledge.jar

# 或直接运行
mvn spring-boot:run

服务启动后,默认运行在 http://localhost:8080。

第四步: 创建知识库

通过系统的可视化界面创建知识库:

填写知识库名称、编码和描述
系统自动分配为用户级知识库
创建成功后即可上传文档

💡 你也可以通过 API 创建,具体接口可参考后端服务代码。

第五步: 上传文档

通过系统界面上传文档:

上传 Markdown 文件 (无需转换,直接解析):

选择文件并填写文档信息 (标题、作者等)
系统自动开始处理

上传 PDF 文件 (需要 MinerU 转换服务):

同样通过文件上传功能
系统后台自动调用 MinerU 进行转换

💡 上传后系统自动创建摄入任务,后台开始处理文档。

第六步: 查看摄入进度

在文档列表中查看文档状态和处理阶段:

状态说明:

PENDING — 待处理
PROCESSING — 处理中
SUCCESS — 成功
FAILED — 失败

处理阶段:

CONVERT — 格式转换中
SPLIT — 分片处理中
VECTORIZE — 向量化中

等待状态变为 SUCCESS,说明文档已处理完成,可用于检索和问答。

💡 系统界面会实时展示文档的处理进度,包括分片数量、向量化数量等信息。

第七步: 发起 RAG 问答

Standard RAG 模式 (默认)

在问答界面输入问题,系统自动从知识库中检索相关内容并生成回答:

输入你的问题,如 "什么是分布式锁?"
选择要检索的知识库
系统实时流式输出回答

启用混合检索与重排序

对于需要更高精度的场景:

开启混合检索开关 — 结合关键词和语义检索
系统自动使用 RRF 融合算法提升召回质量

Agentic RAG 模式

对于复杂的对比分析问题:

切换到 Agent 模式
LLM 自主决定检索策略,可多次检索不同方面的知识
适合 "对比 Redis 和 ZooKeeper 实现分布式锁的优缺点" 这类复杂问题

💡 系统界面提供便捷的 mode 切换按钮,无需编写任何代码即可体验不同 RAG 模式。

RAG 问答界面

在此处添加问答界面截图,展示 Standard 和 Agent 两种模式

第八步: 体验流式响应

系统采用 SSE (Server-Sent Events) 实现流式输出,回答内容实时展示:

响应流顺序:

会话 ID — 标识当前对话
引用文档 — 展示参考来源
思考过程 — 深度思考模式下的推理内容 (可选)
回答内容 — 逐步输出的回答
Token 使用量 — 展示消耗的 Token 数
结束标记 — 回答完成

前端体验:

文字逐个出现,而非等待全部生成后显示
引用文档可点击,查看原文高亮
深度思考模式可展示模型的推理过程

💡 流式响应的技术细节详见流式响应协议,包含完整的前端集成示例。

完整配置示例 (生产环境推荐)

yaml

molandev:
  rag:
    # 分片配置
    splitting:
      chunk-size: 1000
      overlap-size: 200
      min-chunk-size: 100
    
    # 检索配置
    retrieval:
      top-k: 20
      threshold: 0.4
    
    # 混合检索
    hybrid-search:
      enabled: true
      fusion-strategy: rrf
      vector-weight: 0.5
      keyword-weight: 0.5
    
    # 重排序
    rerank:
      enabled: true
      model: qwen3-rerank
      api-url: https://dashscope.aliyuncs.com/compatible-api/v1/reranks
      api-key: ${DASHSCOPE_API_KEY}
      top-n: 5
    
    # 上下文扩展
    context-expansion:
      enabled: true
      before-chunks: 1
      after-chunks: 1
    
    # Elasticsearch
    elasticsearch:
      enabled: true
    
    # 文档摄入
    ingest:
      max-concurrent-tasks: 3
      poll-interval-minutes: 10
      max-retry: 3

常见问题

1. Embedding 模型怎么选?

场景	推荐模型	维度
中文优先	通义千问 text-embedding-v3	1024/1536
多语言	OpenAI text-embedding-3-small	1536
本地部署	Ollama nomic-embed-text	768

2. Chat 模型怎么选?

场景	推荐模型
高性价比	DeepSeek-V3
中文能力强	通义千问 qwen-plus
本地部署	Ollama qwen2.5:72b

3. 为什么我的检索结果不准确?

检查相似度阈值 — threshold 默认 0.4,可调高至 0.6-0.7
启用重排序 — rerank.enabled: true 提升精度
优化分片大小 — chunk-size 过大或过小都会影响效果

4. Lucene 和 Elasticsearch 怎么选?

特性	Elasticsearch	Lucene
内存占用	高 (2GB+)	低 (100MB 内)
部署复杂度	需独立部署	内嵌,无需额外部署
适用场景	生产环境	低配服务器 / Demo 测试
推荐	✅ 生产环境首选	⚠️ 仅建议测试环境

下一步

深入了解架构设计
了解文档摄入完整流程
探索 RAG 问答两种模式
查看配置说明了解所有配置项

快速入门 ​

前置条件 ​

必需组件 ​

可选组件 ​

第一步: 初始化数据库 ​

PostgreSQL 配置 ​

MySQL 配置 ​

第二步: 配置应用 ​

第三步: 启动服务 ​

第四步: 创建知识库 ​

第五步: 上传文档 ​

第六步: 查看摄入进度 ​

第七步: 发起 RAG 问答 ​

Standard RAG 模式 (默认) ​

启用混合检索与重排序 ​

Agentic RAG 模式 ​

第八步: 体验流式响应 ​

完整配置示例 (生产环境推荐) ​

常见问题 ​

1. Embedding 模型怎么选? ​

2. Chat 模型怎么选? ​

3. 为什么我的检索结果不准确? ​

4. Lucene 和 Elasticsearch 怎么选? ​

下一步 ​