DB-GPT Confluence 知识库问答实操指南

DB-GPT Confluence 知识库问答实操指南

【免费下载链接】DB-GPTopen-source agentic AI data assistant for the next generation of AI + Data products.项目地址: https://gitcode.com/GitHub_Trending/db/DB-GPT

入职第一周，你被问过五次"测试环境怎么配"和"发布审批走哪个流程"。答案其实都在团队每天在用的 Confluence 里，但它的搜索框只认精确关键词，换个问法就搜不到。DB-GPT 是一个开源的数据库领域大模型框架，其中的知识库问答（KBQA）能力可以把 Confluence 页面变成一个可以自然语言提问的知识库：文档导入后，直接问"新人入职流程有哪些步骤"，它会给出答案并标出来源页面。本文带你把单个 Confluence 空间接入 DB-GPT，跑通从取数到问答的完整链路。

接入完成后的效果

先把结果说清楚，接入并导入一个空间后：

• 检索从关键词匹配变成语义匹配：问"连接池耗尽怎么处理"，能命中标题为"数据库连接数上限排查"的页面；
• 每个答案都能溯源到具体 Confluence 页面，方便二次确认；
• 按空间建库，检索范围从全库缩到单个空间，跨团队文档不会互相干扰。

可以直接尝试的问句：

• "新员工入职流程有哪些步骤？"
• "微服务之间用什么通信协议？"
• "远程办公政策写在哪份文档里？"

原理一句话：原文进向量库，答案由检索加生成

Confluence 页面导出为纯文本后，DB-GPT 先按固定长度切块（chunking，即把长文切成小段），再交给嵌入模型（把文本转成可计算相似度的数字向量）写入向量库；提问时先检索出最相关的几个文本块，连同问题一起交给大模型生成回答。这套"先检索、再生成"的流程叫 RAG（Retrieval Augmented Generation，检索增强生成），好处是回答始终基于你的文档，而不是模型的自由发挥。

准备清单：版本、配置与模型

先用git clone https://gitcode.com/GitHub_Trending/db/DB-GPT拉取代码，然后核对下表：

实操主线：四步从取数到问答

第一步：抓取 Confluence 页面并转成纯文本

DB-GPT 目前没有内置 Confluence 连接器，用atlassian官方 SDK 把页面拉下来，转成纯文本文件落盘，后面统一导入。脚本核心如下：

from atlassian import Confluence from bs4 import BeautifulSoup confluence = Confluence( url="https://your-domain.atlassian.net/wiki", username="you@example.com", password="your-api-token", cloud=True, # Server/Data Center 版本改为 False ) def fetch_space(space_key, out_dir="confluence_docs"): pages = confluence.get_all_pages_from_space(space_key, expand="body.storage") for page in pages: html = page["body"]["storage"]["value"] text = BeautifulSoup(html, "html.parser").get_text() # 标记语言转纯文本 lines = [ f"标题: {page['title']}", f"来源: {page['_links']['base']}{page['_links']['webui']}", f"更新时间: {page['version']['when']}", "", text, ] with open(f"{out_dir}/{page['id']}.txt", "w", encoding="utf-8") as f: f.write("\n".join(lines)) # 来源 URL 写入文档头部，问答时可溯源

要点：expand="body.storage"用于拿到页面正文；每份文档头部固定写入标题、来源 URL、更新时间，这三行元信息对后续溯源和增量同步都有用。

第二步：配置向量存储与嵌入模型

编辑 configs/dbgpt-bm25-rag.toml，关键段如下：

[rag] chunk_size = 1000 # 每块约 1000 字符，过大影响检索精度 chunk_overlap = 100 # 相邻块重叠，避免句子被切断 similarity_top_k = 5 # 每次提问检索的文本块数量 similarity_score_threshold = 0.0 # 相似度下限，低分块会被过滤 [rag.storage.vector] type = "chroma" # 默认本地 Chroma，无需额外部署 persist_path = "pilot/data" # 向量库落盘目录 [[models.embeddings]] name = "text2vec-large-chinese" # 中文嵌入模型，需已下载到 models/

说明：向量库选型（Chroma、Milvus、OceanBase 等）与切换方式见 KBQA FAQ；嵌入模型维度决定向量维度，换模型时注意旧库需要重建。

第三步：创建知识空间并导入文档

DB-GPT 的知识管理 API 见 examples/client/knowledge_crud_example.py，最小可用片段：

import glob, asyncio from dbgpt_client import Client from dbgpt_client.knowledge import create_space, create_document from dbgpt_client.schema import SpaceModel, DocumentModel async def main(): client = Client(api_key="dbgpt") space = await create_space(client, SpaceModel( name="confluence-prod", # 对应 Confluence PROD 空间 vector_type="Chroma", desc="Confluence PROD 空间文档", owner="dbgpt", )) for f in sorted(glob.glob("confluence_docs/*.txt")): with open(f, encoding="utf-8") as fp: await create_document(client, DocumentModel( space_id=str(space.id), doc_name=f.split("/")[-1], doc_type="TEXT", doc_content=fp.read(), )) await client.aclose() asyncio.run(main())

导入完成后，服务端会对文档执行切块、向量化、建索引；走 Web 界面时也可以直接在"知识库"页面上传.txt文件，效果等价。

第四步：检索相关文本块并生成回答

想验证检索质量，可以先跳过对话界面直接跑检索，参考 examples/rag/embedding_rag_example.py：

import asyncio, os from dbgpt.rag.embedding import DefaultEmbeddingFactory from dbgpt_ext.rag import ChunkParameters from dbgpt_ext.rag.assembler import EmbeddingAssembler from dbgpt_ext.rag.knowledge import KnowledgeFactory from dbgpt_ext.storage.vector_store.chroma_store import ChromaStore, ChromaVectorConfig async def main(): knowledge = KnowledgeFactory.from_file_path("confluence_docs/onboarding.txt") store = ChromaStore( ChromaVectorConfig(persist_path="./pilot/data"), name="confluence_kb", embedding_fn=DefaultEmbeddingFactory( default_model_name=os.path.join( "models", "text2vec-large-chinese")).create(), ) assembler = EmbeddingAssembler.load_from_knowledge( knowledge=knowledge, chunk_parameters=ChunkParameters(chunk_strategy="CHUNK_BY_SIZE"), index_store=store, ) assembler.persist() # 切块 + 向量化 + 写入索引 retriever = assembler.as_retriever(3) # 取 top 3 最相关文本块 chunks = await retriever.aretrieve_with_scores("测试环境怎么配置", 0.3) for c in chunks: print(c.score, c.content[:80]) asyncio.run(main())

要得到"生成式回答"而不是文本块，走 Agent 路线即可：SummaryAssistantAgent会先检索再让大模型总结，完整示例见 examples/agents/retrieve_summary_agent_dialogue_example.py；日常使用则直接打开 DB-GPT Web 端选择该知识空间提问。

调优细节：增量同步、权限过滤与检索参数

• 增量同步：不用每次全量拉取，CQL 里加时间条件即可，如space = PROD AND lastModified >= '2026-09-01'，再按文档头部的"更新时间"行跳过未变化的页面。
• 权限过滤：把页面的view permissions写入文档元数据（或头部元信息），检索结果返回后按当前用户过滤，避免 A 团队页面进入 B 团队的回答。
• 检索参数：similarity_top_k控制召回块数，similarity_score_threshold控制过滤下限，rerank_top_k控制重排序（rerank，用更精细的模型对召回块二次排序）后保留的数量，三者在[rag]段调节。
• 并发：[rag] max_threads控制文档处理线程数，导入大批量页面时调大；问答侧并发由服务端 worker 数决定。

用法示范：按角色直接复制的问句

• 研发："微服务之间用什么通信协议？" / "数据库连接数耗尽怎么排查？"
• 人事："新员工入职流程有哪些步骤？" / "年度体检怎么预约？"
• 销售："金融行业有哪些客户案例？" / "企业版定价标准是什么？"
• 管理者："Q3 产品路线图最近一次更新是什么时候？"

踩坑记录：导入与检索的三个常见问题

现象：运行导入时报text2vec-large-chinese not found。原因：嵌入模型是本地文件，仓库默认不带模型权重。处理：先安装 git-lfs，再把 text2vec-large-chinese 克隆到models/目录，步骤见 KBQA FAQ。

现象：导入的文档里混着标记符号，答案可读性差。原因：直接把 Confluence 的body.storage存储格式标记语言当纯文本用了。处理：用 BeautifulSoup 的get_text()先转纯文本再落盘（见第一步脚本）。

现象：简单问题答非所问，或引用了不相关页面。原因：低相似度文本块未被过滤，或chunk_size过大导致一个块里混了多段内容。处理：在 configs/dbgpt-bm25-rag.toml 中提高similarity_score_threshold，并尝试把chunk_size降到 500~800、chunk_overlap保持在 100 左右重新导入。

收尾：资源索引与参与方式

本文的完整链路是：用 SDK 把 Confluence 页面转成带元信息的纯文本 → 配置 Chroma 向量库与中文嵌入模型 → 通过知识空间 API 建库导入 → 用 RAG 检索加生成完成问答。整套方案只依赖本地向量库，文档不出内网，后续扩展更多空间或接入其他文档源，只需复用第一步的取数脚本和第三、四步的代码。

• 知识库 API 文档：docs/docs/api/knowledge.md
• RAG 模块说明：docs/docs/modules/rag.md
• KBQA 常见问题：docs/docs/faq/kbqa.md
• 向量存储配置参考：docs/docs/config-reference/vector_store/index.mdx

如果你在接入自己的 Confluence 实例时遇到脚本适配、权限模型或其他问题，欢迎到仓库提交 Issue 或 PR，把踩过的坑写进文档里。

【免费下载链接】DB-GPTopen-source agentic AI data assistant for the next generation of AI + Data products.项目地址: https://gitcode.com/GitHub_Trending/db/DB-GPT