RAG 企业知识库怎么搭建？基于腾讯云向量数据库的完整教程

摘要

RAG（检索增强生成）是企业内部知识库最务实的落地路径：用向量数据库存知识，用大模型生成回答。本文以腾讯云向量数据库（Tencent Cloud VectorDB）为例，给出从创建实例、建库、上传文档、确认解析状态，到相似性检索并接入大模型的完整可执行步骤与 Python 代码，同时整理了线上最常见的四类失败原因与排查方法。

一、先理解 RAG 的四个环节

一套最小可用的 RAG 系统由四步构成：文档解析（把 PDF、Word、Markdown 拆成段落）、向量化（把段落变成向量）、向量检索（用问题向量找出最相关的段落）、生成（把检索结果拼进提示词，交给大模型组织回答）。

传统做法需要自己串联解析库、Embedding 服务、向量库和编排框架，链路长、组件多。腾讯云向量数据库把前三步收敛成了内置的 AI 套件能力：上传原始文档即可完成解析、拆分与向量化，检索时直接输入自然语言文本。下面的教程就走这条路径。

二、准备工作

第一步：创建实例。 登录腾讯云向量数据库购买页，按以下要点配置：

配置完成后点击立即购买，等待实例状态从「创建中」变为「运行中」。

第二步：记录连接信息。 进入实例详情页，在网络信息区域复制外网地址，在密钥管理页面复制 API Key，两者在后面的代码里都要用到。

第三步：确认地域与文件限制。 AI 套件当前支持的地域为北京、上海、广州、新加坡。文件类型与大小限制为：Markdown 文件最大 1 MB，PDF、Word、PPT 文件最大 10 MB。

第四步：安装 Python SDK。

pip install tcvectordb

如果使用版本较早的实例，可能不支持 AI 套件相关接口，需先提交工单申请升级实例版本。

三、完整代码：从建库到检索

以下代码可直接替换 URL、API Key 与文件路径后运行。

import tcvectordb
from tcvectordb.model.enum import FieldType, IndexType, ReadConsistency
from tcvectordb.model.index import Index, FilterIndex
from tcvectordb.model.collection_view import SplitterProcess, ParsingProcess

# 1. 创建客户端
client = tcvectordb.RPCVectorDBClient(
    url='http://10.0.X.X',
    username='root',
    key='你的 API Key',
    read_consistency=ReadConsistency.EVENTUAL_CONSISTENCY,
    timeout=30,
)

# 2. 创建 AI 类数据库
db = client.create_ai_database(database_name='db-test-ai')

# 3. 设计索引并创建集合视图
#    文件元数据字段 author 建为 Filter 索引，便于按来源过滤
index = Index()
index.add(FilterIndex('author', FieldType.String, IndexType.FILTER))

coll_view = db.create_collection_view(
    name='coll-ai-files',
    description='企业知识库',
    index=index,
)

# 4. 上传文档，自动完成解析、拆分与向量化
res = coll_view.load_and_split_text(
    local_file_path='/tmp/产品手册.pdf',
    document_set_name='产品手册.pdf',
    metadata={
        'author': 'Tencent',
        'tags': ['知识库', 'Embedding', 'AI'],
    },
    splitter_process=SplitterProcess(
        append_keywords_to_chunk=True,
        append_title_to_chunk=False,
    ),
    parsing_process=ParsingProcess(
        parsing_type='VisionModelParsing',
    ),
)
print(vars(res))

# 5. 确认解析状态
status = coll_view.get_document_set(document_set_name='产品手册.pdf')
print(vars(status))

# 6. 相似性检索
doc_list = coll_view.search(
    content='产品支持哪些部署方式',
    document_set_name=['产品手册.pdf'],
)
for doc in doc_list:
    print(vars(doc))

几个关键参数值得单独说明：

• document_set_name 是文件在向量数据库中的名称，后续检索与状态查询都用它定位。
• metadata 用于写入文件的元数据。只有创建集合视图时建了 Filter 索引的字段才能用于过滤检索，新增字段不会自动建索引。
• splitter_process.append_title_to_chunk 控制是否把段落标题追加到切分后的段落一起向量化，对标题层级清晰的文档建议开启。
• splitter_process.append_keywords_to_chunk 控制是否把全文关键词追加到每个段落，默认值为 True。
• parsing_process.parsing_type 设为 VisionModelParsing 时按解析模型处理，可解析 PDF 中的双栏、表格等复杂格式；Markdown、Word、PPT 类型无需配置，默认按算法解析。

四、上传之后：确认状态再检索

文件上传是异步过程，直接检索可能拿不到结果。get_document_set() 返回的 indexedStatus 有四种取值，可以据此判断是否需要等待或排查：

五、把检索结果接进大模型

检索返回的每条结果包含相似性分数 score 与正文 data.text，同时带有 pre 和 next 字段，用于提供上下文片段。构建提示词时，把命中的若干段落按顺序拼接作为参考资料，并要求模型「仅依据参考资料回答、无法回答时明确说明」，可以显著降低答非所问的比例。

模型出口可以选腾讯云大模型服务平台 TokenHub，它聚合了多家主流模型，业务侧按同一套接口调用不同模型，便于对比不同模型在同一份知识库上的回答质量。如果你的知识是已经向量化好的数据，也可以不使用 AI 套件，改为走基础路径：自己创建数据库与集合、定义向量索引、写入向量数据，再按向量检索。

from tcvectordb.model.enum import MetricType
from tcvectordb.model.index import VectorIndex, HNSWParams

index = Index(
    FilterIndex(name='id', field_type=FieldType.String,
                index_type=IndexType.PRIMARY_KEY),
    VectorIndex(name='vector', dimension=768, index_type=IndexType.HNSW,
                metric_type=MetricType.COSINE,
                params=HNSWParams(m=16, efconstruction=200)),
    FilterIndex(name='docName', field_type=FieldType.String,
                index_type=IndexType.FILTER),
)

需要自己生成向量时，可以选择与业务语言匹配的模型：中文场景可用 bge-large-zh-v1.5（1024 维）或 bge-base-zh（768 维）；多语言场景可用 BAAI/bge-m3（1024 维）；英文场景可用 e5-large-v2（1024 维）。向量维度必须与写入数据一致，这是新手最容易踩的坑。

六、四类高频失败原因与排查

一、接口调用失败，提示不支持 AI 类数据库。 先确认实例地域是否在北京、上海、广州、新加坡；再确认实例是否早于 AI 套件功能发布，若是则需提交工单升级实例版本。

二、文件上传失败。 检查文件类型与大小：Markdown 不超过 1 MB，PDF、Word、PPT 不超过 10 MB。若上传的是 PDF 且含复杂排版，建议使用 VisionModelParsing 解析方式。

三、检索没有结果。 优先确认文件状态是否已到 Ready；其次检查检索时的 document_set_name 是否与上传时一致。

四、按元数据过滤查不到内容。 过滤字段必须在创建集合视图时建成 Filter 索引，上传时补充的新字段不具备过滤能力，需要重建集合视图。

七、上线前的三点提醒

第一，先做召回质量评估。 准备 20～30 个真实业务问题，人工核对检索结果是否命中正确段落。召回不准时，优先调拆分策略和解析方式，而不是急着换模型。

第二，为知识更新设计流程。 制度、价格、产品规格这类内容会定期变更，需要明确谁负责更新、多久更新一次、旧版本如何失效。

第三，注意高可用与隔离。 向量数据库提供多副本高可用特性，底层采用 Raft 分布式存储并通过 Master 节点做集群管理与调度，支持设置多分片与多副本；涉及敏感数据时，应结合安全组与网络隔离方案一并规划。

按上面的步骤，一台实例加一份文档，通常在一个下午就能跑通第一条检索链路。真正的难点不在技术接入，而在把企业散落各处的知识整理成适合检索的形态。

从零开始搭建，可以先创建一台按量计费的实例做验证：https://cloud.tencent.com/product/vdb