配置说明

Knowledge 服务提供丰富的配置项,支持灵活的功能组合和性能调优。

基础配置

数据源配置

yaml

spring:
  # MySQL 数据源 (元数据、会话管理)
  datasource:
    url: jdbc:mysql://localhost:3306/knowledge?useUnicode=true&characterEncoding=utf-8
    username: root
    password: ${MYSQL_PASSWORD}
    driver-class-name: com.mysql.cj.jdbc.Driver
  
  # PostgreSQL 数据源 (向量存储,可选,默认使用主数据源)
  datasource:
    dynamic:
      datasource:
        vector:
          url: jdbc:postgresql://localhost:5432/knowledge
          username: postgres
          password: ${PG_PASSWORD}
          driver-class-name: org.postgresql.Driver

Spring AI 配置

yaml

spring:
  ai:
    openai:
      base-url: https://api.openai.com  # OpenAI 兼容接口
      api-key: ${OPENAI_API_KEY}
      
      # Embedding 模型
      embedding:
        options:
          model: text-embedding-3-small
          dimensions: 1536
      
      # Chat 模型
      chat:
        options:
          model: gpt-4o
          temperature: 0.7
          max-tokens: 4096

向量数据库配置

yaml

spring:
  ai:
    vectorstore:
      pgvector:
        # 向量维度 (需与 Embedding 模型匹配)
        dimensions: 1536
        # 索引类型: HNSW (推荐) / IVFFlat
        index-type: HNSW
        # 距离类型: COSINE_DISTANCE (推荐) / EUCLIDEAN_DISTANCE / NEGATIVE_INNER_PRODUCT
        distance-type: COSINE_DISTANCE
        # 是否自动初始化表结构
        initialize-schema: true

Knowledge 配置

完整配置项

yaml

molandev:
  rag:
    # ==================== 文档解析 ====================
    parsing:
      # 支持的文档类型
      supported-types: pdf,doc,docx,xls,xlsx,ppt,pptx,txt,md,html
      # 最大文件大小 (MB)
      max-file-size: 100
      # 解析超时时间 (秒)
      parse-timeout: 300

    # ==================== 文档切片 ====================
    splitting:
      # 切片大小 (字符数)
      chunk-size: 1000
      # 切片重叠大小 (字符数)
      overlap-size: 200
      # 最小块大小
      min-chunk-size: 100

    # ==================== 向量化 ====================
    embedding:
      # 批处理大小
      batch-size: 10
      # 批次间延迟 (毫秒), 避免 API 限流
      batch-delay-ms: 100

    # ==================== 检索 ====================
    retrieval:
      # 返回结果数量
      top-k: 20
      # 相似度阈值 (0-1)
      threshold: 0.4

    # ==================== 重排序 ====================
    rerank:
      # 是否启用重排序
      enabled: false
      # 重排序模型
      model: qwen3-rerank
      # API 地址
      api-url: https://dashscope.aliyuncs.com/compatible-api/v1/reranks
      # API Key
      api-key: ${DASHSCOPE_API_KEY}
      # 重排序后返回的结果数量
      top-n: 5

    # ==================== 上下文补全 ====================
    context-expansion:
      # 是否启用上下文补全
      enabled: false
      # 向前扩展的 chunk 数量
      before-chunks: 1
      # 向后扩展的 chunk 数量
      after-chunks: 1

    # ==================== Elasticsearch ====================
    elasticsearch:
      # 是否启用 ES 全文检索
      enabled: false
      # ES 连接地址
      uris: http://localhost:9200
      # ES 认证 (可选)
      username: elastic
      password: ${ES_PASSWORD}

    # ==================== Lucene ====================
    lucene:
      # 是否启用 Lucene 全文检索 (低配服务器/Demo 测试,不建议生产)
      enabled: false
      # Lucene 索引存储路径
      index-dir: ./lucene-index

    # ==================== 混合检索 ====================
    hybrid-search:
      # 向量检索权重 (0-1)
      vector-weight: 0.5
      # 关键词检索权重 (0-1)
      keyword-weight: 0.5

    # ==================== 文档转换服务 ====================
    converter:
      # MarkItDown 转换服务
      mark-it-down-url: http://localhost:10996
      # LibreOffice 转换服务
      libre-office-url: http://localhost:10997
      # MinerU 转换服务
      mineru-url: http://localhost:10998
      # 连接超时 (秒)
      connect-timeout: 30
      # 读取超时 (秒)
      read-timeout: 60

    # ==================== 文档摄入任务 ====================
    ingest:
      # 是否启用摄入任务
      enabled: true
      # 轮询间隔 (分钟)
      poll-interval-minutes: 10
      # 最大并发任务数
      max-concurrent-tasks: 3
      # 最大重试次数
      max-retry: 3
      # 任务超时时间 (分钟)
      task-timeout-minutes: 30

    # ==================== Agent 模式 ====================
    # 注意: Agent 模式由前端请求的 mode 参数控制,无需在此配置
    # 此配置仅用于控制 Agent 的行为参数
    agent:
      # Agent 最大工具调用次数 (防止无限循环)
      max-tool-calls: 5
      # 是否启用查询改写
      enable-query-rewrite: true
      # 是否启用元数据提取
      enable-metadata-extraction: true

  # ==================== 聊天配置 ====================
  ai:
    chat:
      # 最大上下文 Token 数
      max-context-tokens: 32768
      # 最大消息数量
      max-message-count: 20

配置项详解

分片配置 (`molandev.rag.splitting`)

配置项	默认值	说明
`chunk-size`	1000	分片大小,影响检索粒度
`overlap-size`	200	重叠大小,避免边界截断
`min-chunk-size`	100	最小分片,过滤过小片段

调优建议:

场景	chunk-size	说明
短文档 (FAQ)	300-500	保持完整性
技术文档	800-1200	平衡语义与检索精度
长文档 (书籍)	1000-1500	配合上下文补全

检索配置 (`molandev.rag.retrieval`)

配置项	默认值	说明
`top-k`	20	召回数量,影响覆盖度
`threshold`	0.4	相似度阈值,影响精度

调优建议:

场景	top-k	threshold
高召回场景	30	0.3
高精度场景	10	0.6-0.7

重排序配置 (`molandev.rag.rerank`)

配置项	默认值	说明
`enabled`	false	是否启用
`model`	qwen3-rerank	重排序模型
`top-n`	5	精排后返回数量
`api-url`	DashScope	重排序 API 地址
`api-key`	-	API Key

成本考虑: 重排序需调用外部 API,有额外成本。

上下文补全配置 (`molandev.rag.context-expansion`)

配置项	默认值	说明
`enabled`	false	是否启用
`before-chunks`	1	向前扩展数
`after-chunks`	1	向后扩展数

调优建议:

场景	before-chunks	after-chunks
短分片	2	2
长分片	1	1

文档摄入配置 (`molandev.rag.ingest`)

配置项	默认值	说明
`enabled`	true	是否启用摄入任务
`poll-interval-minutes`	10	轮询间隔 (分钟)
`max-concurrent-tasks`	3	最大并发任务数 (信号量控制)
`max-retry`	3	最大重试次数
`task-timeout-minutes`	30	任务超时时间 (分钟)

Agent 模式配置 (`molandev.rag.agent`)

注意: Agent 模式的启用由前端请求的 mode 参数控制 (mode=agentic),而非配置文件。此配置仅用于调整 Agent 的行为参数。

配置项	默认值	说明
`max-tool-calls`	5	最大工具调用次数 (防止无限循环)
`enable-query-rewrite`	true	是否启用查询改写
`enable-metadata-extraction`	true	是否启用元数据提取

场景化配置

最小化配置

适合开发测试,资源消耗最低:

yaml

molandev:
  rag:
    splitting:
      chunk-size: 1000
      overlap-size: 200
    retrieval:
      top-k: 10
      threshold: 0.4
    rerank:
      enabled: false
    context-expansion:
      enabled: false
    elasticsearch:
      enabled: false
    lucene:
      enabled: false  # 低配服务器可设为 true
    agent:
      enabled: false

标准模式

平衡效果与成本,适合日常使用:

yaml

molandev:
  rag:
    splitting:
      chunk-size: 1000
      overlap-size: 200
    retrieval:
      top-k: 20
      threshold: 0.4
    rerank:
      enabled: true
      top-n: 5
    context-expansion:
      enabled: true
      before-chunks: 1
      after-chunks: 1
    elasticsearch:
      enabled: false  # 或 true,视资源情况
    agent:
      enabled: false

生产环境推荐 (完整模式)

最佳检索效果,生产环境推荐配置:

yaml

molandev:
  rag:
    splitting:
      chunk-size: 1000
      overlap-size: 200
      min-chunk-size: 100
    retrieval:
      top-k: 20
      threshold: 0.4
    hybrid-search:
      vector-weight: 0.5
      keyword-weight: 0.5
    rerank:
      enabled: true
      top-n: 5
    context-expansion:
      enabled: true
      before-chunks: 1
      after-chunks: 1
    elasticsearch:
      enabled: true
    ingest:
      max-concurrent-tasks: 3
      poll-interval-minutes: 10
      max-retry: 3
    # Agent 模式由前端 mode 参数控制,此处仅配置行为参数
    agent:
      max-tool-calls: 5

高精度模式

追求最高准确率,适合专业问答场景:

yaml

molandev:
  rag:
    retrieval:
      top-k: 30
      threshold: 0.6
    rerank:
      enabled: true
      top-n: 3
    hybrid-search:
      vector-weight: 0.6
      keyword-weight: 0.4
    context-expansion:
      enabled: true
      before-chunks: 2
      after-chunks: 2
    elasticsearch:
      enabled: true

多厂商模型支持

Embedding 模型

yaml

# OpenAI
spring.ai.openai.base-url: https://api.openai.com
spring.ai.openai.embedding.options.model: text-embedding-3-small

# DeepSeek
spring.ai.openai.base-url: https://api.deepseek.com
spring.ai.openai.embedding.options.model: deepseek-embedding

# 通义千问
spring.ai.openai.base-url: https://dashscope.aliyuncs.com/compatible-mode/v1
spring.ai.openai.embedding.options.model: text-embedding-v3

# Ollama 本地部署
spring.ai.openai.base-url: http://localhost:11434/v1
spring.ai.openai.embedding.options.model: nomic-embed-text

Chat 模型

yaml

# OpenAI
spring.ai.openai.chat.options.model: gpt-4o

# DeepSeek
spring.ai.openai.base-url: https://api.deepseek.com
spring.ai.openai.chat.options.model: deepseek-chat

# 通义千问
spring.ai.openai.base-url: https://dashscope.aliyuncs.com/compatible-mode/v1
spring.ai.openai.chat.options.model: qwen-plus

# Ollama 本地部署
spring.ai.openai.base-url: http://localhost:11434/v1
spring.ai.openai.chat.options.model: qwen2.5:72b

配置优先级

检索参数支持多级配置,优先级从高到低:

API 请求参数 — 单次请求指定
代码默认值 — RagContext 构建时指定
配置文件 — application.yml

java

// API 请求参数优先级最高
RetrievalOptions options = RetrievalOptions.builder()
        .topK(10)  // 覆盖配置文件的 top-k: 20
        .build();

环境变量

推荐使用环境变量管理敏感配置:

yaml

spring:
  datasource:
    password: ${MYSQL_PASSWORD}
  ai:
    openai:
      api-key: ${OPENAI_API_KEY}

molandev:
  rag:
    rerank:
      api-key: ${DASHSCOPE_API_KEY}
    elasticsearch:
      password: ${ES_PASSWORD}

下一步

查看检索系统了解检索架构与调优
查看 RAG 问答了解两种 RAG 模式

配置说明 ​

基础配置 ​

数据源配置 ​

Spring AI 配置 ​

向量数据库配置 ​

Knowledge 配置 ​

完整配置项 ​

配置项详解 ​

分片配置 (molandev.rag.splitting) ​

检索配置 (molandev.rag.retrieval) ​

重排序配置 (molandev.rag.rerank) ​

上下文补全配置 (molandev.rag.context-expansion) ​

文档摄入配置 (molandev.rag.ingest) ​

Agent 模式配置 (molandev.rag.agent) ​

场景化配置 ​

最小化配置 ​

标准模式 ​

生产环境推荐 (完整模式) ​

高精度模式 ​

多厂商模型支持 ​

Embedding 模型 ​

Chat 模型 ​

配置优先级 ​

环境变量 ​

下一步 ​

配置说明

基础配置

数据源配置

Spring AI 配置

向量数据库配置

Knowledge 配置

完整配置项

配置项详解

分片配置 (`molandev.rag.splitting`)

检索配置 (`molandev.rag.retrieval`)

重排序配置 (`molandev.rag.rerank`)

上下文补全配置 (`molandev.rag.context-expansion`)

文档摄入配置 (`molandev.rag.ingest`)

Agent 模式配置 (`molandev.rag.agent`)

场景化配置

最小化配置

标准模式

生产环境推荐 (完整模式)

高精度模式

多厂商模型支持

Embedding 模型

Chat 模型

配置优先级

环境变量

下一步