G 层部署指南 · 企业落地
一页读懂这一部分：把模型变成"公司里能用的东西"。 A–F 解决的是"技术跑通"，G 部分解决的是"业务能用、数据安全、有人负责"。 本部分共 10 课，是全体系里内容最多、也最贴企业采购决策的一块。
本指南是 G 部分 10 课的浓缩版，按四个块组织（私有化与安全 / 知识库建设 / 检索与问答 / 评估与容量）， 只保留"装什么、干什么用、怎么装、怎么验"。
〇、这一部分是什么（职能）
| 项 | 内容 |
|---|---|
| 位置 | 跨 L4 应用层 + 业务侧 —— 它引进了新零件（向量库、检索、权限、评估） |
| 一句话职责 | 把大模型变成企业里能用的业务系统。 |
| 官方依据 | 官方四大开发场景中的推理开发里，MindSDK（RAG SDK 等）这一半 |
| 它回答的三个企业问题 | 私有化能不能落地 / 私有知识库怎么搭 / 数据安全谁负责 |
⭐ 10 课一览（按四个块分组）
| 块 | 课 | 一句话 |
|---|---|---|
| ① 私有化与安全 | G1 私有化部署 | 私有化 = 部署位置 / 数据流向 / 资产保护 |
| G9 企业安全 | 权限 / 隔离 / 审计 —— 哪些官方给了、哪些要自己做 | |
| ② 知识库建设 | G2 RAG 基础 | 企业为什么需要私有知识库 |
| G3 知识库搭建 | 装 SDK + 建库 + 灌数据 | |
| G4 文档解析与切分 | 一次做完、后面全受影响的一步 | |
| ③ 检索与问答 | G5 检索与精排 | 为什么有的答得准有的答不准 |
| G6 问答编排 | 把检索、大模型、缓存串成链路 | |
| G10 进阶检索 | 知识图谱与链式检索，什么时候需要 | |
| ④ 评估与容量 | G7 效果评估 | 怎么向客户证明这套管用 |
| G8 容量与成本 | 要几台机器、卡怎么分 |
一、块一 · 私有化与安全（G1 + G9）
1.1 ⭐ 私有化 = 三件事，不是一件事
| 件 | 要回答的问题 |
|---|---|
| ① 部署位置 | 无外网能不能装完、能跑起来 |
| ② 数据流向 | 每条数据去了哪，能不能解释 |
| ③ 资产保护 | 模型被拷走了，能不能用 |
多数人只做第一件，就以为做完了。
命令 ss -ntp
含义：看本机正在和谁通着话（已建立的 TCP 连接） 拆解：去掉
-l就是"不看监听的，看已建立的"；-p显示进程 用法：跑起完整业务流程后再执行 期望：只有内网地址之间的连接 不过会怎样：出现连到公网 IP 的 ESTABLISHED 连接 → 这就是一条外发通道，必须查清
1.2 官方给的真东西（网上基本没人讲）
① PMCC 模型混淆（CANN 层）
官方原文：PMCC（Privacy & Model Confidential Computing）模型混淆特性， 利用 CPU 核中的 TrustZone 可信执行环境隔离存储混淆因子、 派生混淆掩码、执行动态掩码添加。
接口：aclnnObfuscationSetup / aclnnObfuscationCalculate / aclnnCrypto
⚠️ 约束：官方明确 Ascend 950PR / 950DT 对 aclnnObfuscationCalculate 不支持 → 选型先查型号。
② AVI（Ascend Virtual Instance，昇腾虚拟化实例）
把 1 个 NPU 切分成若干 vNPU 挂载到虚拟机 / 容器， 实现资源虚拟化复用并保证资源安全隔离，支持多租户按需申请 / 回收。
| 类型 | 隔离程度 |
|---|---|
| 硬件虚拟化（vNPU） | AICore / AICPU / 内存等资源相互隔离，任务互不影响（真隔离） |
| 软件虚拟化 | 创建虚拟实例，共享硬件资源（逻辑隔离） |
1.3 ⭐⭐ 官方对安全加固的态度（这句话本身就是结论）
官方《加固须知》原文：本文中列出的安全加固措施为基本的加固建议项。 用户应根据自身业务，重新审视整个系统的网络安全加固措施， 应按照所在组织的安全策略进行相关配置。
→ 官方给的是底线，不是全套；最终责任在使用方。
1.4 企业安全 = 三件事 × 三档（G9）
| 三件事 | 官方给了直接用 | 官方给机制、你定策略 | 官方没给、要自己接 |
|---|---|---|---|
| 权限 | 知识库归属查询权限（接口有 user_id / role） |
role 只有 admin / member 两档 |
⭐ 业务级权限体系 |
| 隔离 | AVI / vNPU 资源隔离 | 隔离到什么粒度由你定 | 租户配额、计费 |
| 审计 | MindIE 日志（MINDIE_LOG_PATH / MINDIE_LOG_ROTATE，默认 20MB×10） |
记什么、留多久 | ⭐ 审计字段设计 / 留存期限 / SIEM 告警 |
⭐⭐ 一条必须记住的官方边界：
RAG SDK「不包含用户、权限等和业务强相关的功能接口」。
→ 权限体系要自己做。 官方给的是知识库归属查询权限（谁建的库谁能查）， 不是"业务级权限"（哪个部门能看哪份文件）。
命令 python3 -c "from mx_rag.knowledge import KnowledgeStore; ..."
含义：知识库权限的三个动作 拆解：
add_knowledge（建库）／add_usr_id_to_knowledge（把用户加进库）／delete_usr_id_from_knowledge（移除） 用法：按官方《知识管理》示例 期望：用户 ID 与知识库绑定成功 不过会怎样：user_id有正则约束^[a-zA-Z0-9_-]{6,64}$—— 写中文用户名直接报错
⚠️ 官方明确没给的（要自己接的十项，节选）： 审计字段设计 / 留存期限 / SIEM 告警 / 应用层操作审计接口 / 认证与令牌生命周期 / 细粒度数据权限 / 租户配额 / 数据加密方案与密钥管理 / 等保级别 / 数据分级。
1.5 ⚠️ 一条安全警告（官方原文，必须记住）
RAG SDK 如果使用 Cache 对问题-答案缓存，生成的数据库未做加密存储， 如果涉及银行卡号、身份证号、护照号、口令等个人数据，请勿存放到数据库中。
二、块二 · 知识库建设（G2 + G3 + G4）
2.1 为什么需要它（G2）
官方点名大模型的三个毛病：准确性不足 / 知识更新速度慢 / 答案透明度欠缺。 RAG「通过为大模型接入外部知识库，有效提升了问答系统的准确率，解决了大模型的幻觉和时效性问题」。
官方题眼：
RAG 技术能够以较低成本将基础大模型转换为领域专用大模型， 成为提升大模型"最后一公里"落地应用效果的关键技术。
2.2 两条主线八步（这是整个块的地图）
主线一 构建知识库：
① 上传文档 → 加载和切分（注册解析器 + 切分器，产出 chunks）
② 文本向量化（加载 embedding 模型，按模型具体路径配置）
③ 初始化知识库管理（关系库 + 向量库）
主线二 在线问答：
① 初始化缓存（可选，命中直接返回）
② 初始化大模型 Chain（串联 LLM / 检索 / 精排）
③ 初始化检索方式
④ reranker 精排（可选）
⑤ 组装 prompt 传入大模型
⭐ 双库设计（很好记的一对）：
切分后的文本 chunks 存入关系数据库，chunks 向量化后的数据存入向量数据库，一一对应。
向量库负责"按意思找"，关系库负责"把原文给模型" —— 缺一不可。
2.3 怎么装（G3）
包名：Ascend-mindxsdk-mxindex_<版本>_linux-<架构>.run
从哪下：昇腾社区 → MindStudio / MindSDK 软件下载（⚠️ 不在 CANN 下载页）
Python：官方要求 3.11
命令 ./<安装包>.run --install --install-path=<路径>
含义：安装 RAG SDK 拆解：
--install（安装）／--install-path（路径须以/或~开头） 跳许可交互：命令前加echo y |用法：echo y | ./Ascend-mindxsdk-mxindex_<版本>_linux-aarch64.run --install --install-path=/your/path期望：最后出现Install package successfully不过会怎样： - 输入非Y→ 停止安装并退出 - ⚠️ 官方明确：不建议在/tmp路径下安装
命令 pip3 install -r <安装路径>/mxRag/requirements.txt
含义：装依赖 期望：
Successfully installed ...不过会怎样：报Cannot uninstall 'xxx'. It is a distutils installed project→ 官方给的处置：加--ignore-installed重跑
命令 source ~/.bashrc
含义：让刚加进
.bashrc的环境变量在当前终端立刻生效 拆解：source在当前 shell 执行，不新开进程 期望：无输出 不过会怎样：不执行 → 当前终端不生效 ⭐ 这是"我明明配了环境变量为什么还说找不到"的头号原因
⚠️ 要 source 三个：CANN → NNAL/ATB → RAG SDK 自己。
2.4 建库灌数据（最小可跑链路）
from mx_rag.embedding.local import TextEmbedding
from mx_rag.knowledge import KnowledgeStore, KnowledgeDB, upload_files
from mx_rag.document import LoaderMng
from mx_rag.storage.document_store import SQLiteDocstore
from mx_rag.storage.vectorstore import MindFAISS
# ① 解析器与切分器：两边都要注册（实际生效的是"交集"）
loader_mng = LoaderMng()
loader_mng.register_loader(DocxLoader, [".docx"])
loader_mng.register_splitter(RecursiveCharacterTextSplitter, [".docx", ".pdf"])
# ② embedding：dev = 第几张 NPU 卡
emb = TextEmbedding("/path/to/model", dev_id=0)
# ③ 两个库
vector_store = MindFAISS(x_dim=1024, devs=[0], auto_save=True)
chunk_store = SQLiteDocstore(db_path="./sql.db")
knowledge_store = KnowledgeStore(db_path="./sql.db")
# ④ 建库 + ⑤ 灌文档
knowledge_store.add_knowledge(knowledge_name="test", user_id='Default', role='admin')
knowledge_db = KnowledgeDB(knowledge_store=..., knowledge_db=..., knowledge_name="test",
user_id='Default', white_paths=["/home/"])
failed = upload_files(knowledge=knowledge_db, files=["/home/data/a.docx"],
loader_mng=loader_mng, embed_func=emb.embed_documents, force=True)
print("上传失败的文件:", failed)
⭐⭐ 这段代码里有四个"看不出问题、但会出错"的官方约束：
| 点 | 官方约束 | 错了会怎样 |
|---|---|---|
x_dim=1024 |
必须与 embedding 模型输出维度一致 | 换模型忘改 → 检索莫名变差 |
user_id='Default' |
正则 ^[a-zA-Z0-9_-]{6,64}$ |
写中文用户名 → 直接报错 |
db_path="./sql.db" |
禁用含 /etc /usr/bin /sys/ /dev/ /sbin /tmp；不能软链接、不能含 .. |
报路径非法 |
failed（返回值） |
⭐ 返回的是"失败列表"，不是"成功列表" | 只看到"没报错"就以为灌进去了 |
2.5 切分（G4）—— 一次做完、后面全受影响的一步
为什么它最关键：
切太碎答不全、切太大答偏，而且检索阶段救不回来。
两个注册器的交集规则：
register_loader 管读、register_splitter 管切 —— 少一个，那个格式就不生效。
官方示例值（不是最优值）：
RecursiveCharacterTextSplitter(chunk_size=750, chunk_overlap=150)
| 参数 | 调大 | 调小 |
|---|---|---|
chunk_size |
上下文全，但噪声多 | 精准，但话容易被切断 |
chunk_overlap |
少切断，但重复存储 | 省空间，但跨块信息会丢 |
⭐ 官方给的是示例值 → 你的最优值只能用自己的文档试出来（试法见 G7）。
另外三条官方细节：
| 点 | 官方说明 |
|---|---|
load_image |
二选一，不是叠加；且 embed_func 要配套 |
not_summarize_threshold |
默认 30 —— 短于阈值不调模型、直接返回原文 |
ClientParam |
use_http 默认 False 即 HTTPS，且 HTTPS 下 ca_file 必传 |
三、块三 · 检索与问答（G5 + G6 + G10）
3.1 ⭐ 三个调点（G5 的核心）
| 调点 | 位置 | 手段 |
|---|---|---|
| ① 检索前 | 查询改写 | 把用户的话改写成更好检索的形式 |
| ② 检索时 | 近似检索 / BM25 全文检索 | 选对检索方式 |
| ③ 检索后 | reranker 精排 | 把最相关的排到前面 |
官方原话：只用了默认检索的 RAG，效果一定不好。
3.2 ⭐⭐ 官方默认值在三个位置都不站你这边（这是本块最值钱的一条）
| 参数 | 官方默认值 | 意味着 |
|---|---|---|
k |
默认 1 | 只取 1 条 —— 常常不够 |
score_threshold |
默认 None（不使能阈值过滤） |
低质量结果也会被带进来 |
SingleText2TextChain.reranker |
默认 None |
官方示例里确实没传 reranker |
⭐ 结论：「示例能跑通 ≠ 效果调好了」。
⭐ 另一条关键认知：
检索的上限是 topk，不是"库里有"。 官方原文：「使用近似算法…检索相似的 topk 个向量 ID，通过向量 ID 获取关系数据库中 topk 个相关文档」 → 你只取了 1 条，库里有再多也用不上。
可照抄的接口（官方《接口参考》）：
| 接口 | 用途 |
|---|---|
Retriever / MultiQueryRetriever |
基础检索 / 多查询改写 |
BMRetriever / FullTextRetriever |
BM25 / 全文检索 |
Reranker / LocalReranker / TEIReranker / RerankerFactory / MixRetrieveReranker |
精排 |
TextEmbedding / SparseEmbedding / TEIEmbedding / CLIPEmbedding / ImageEmbedding / EmbeddingFactory |
向量化 |
3.3 ⭐⭐ 一条硬规范：接口必须在 try/except 内调用（G6）
官方原文：RAG SDK 接口遵循异常处理机制，故用户必须在 try/except 语句块内进行调用以及异常处理， 防止在使用的过程中出现异常抛出导致程序退出的情况。
⚠️ 特别注意：G3 给的官方示例里没有包 try/except —— 照抄示例上线，一个异常就能让整个服务进程退出。
3.4 串成链路（G6）
| 模块 | 干什么 |
|---|---|
llm_chains |
串联 LLM / 检索 / 精排；支持多轮对话、检索推理并行 |
cache_module |
缓存（可选，命中直接返回） |
prompt_compression |
Prompt 压缩 |
llm_client |
大模型调用 |
⚠️ 两处官方文档自身的坑（原样标出，不当解读）：
- ParallelText2TextChain 返回的 key 是 prompt，而 SingleText2TextChain 是 query —— 名字不一样；
- context_reorder 的说明书写"优先保留相关性低的切片" —— 照字面理解会反。
3.5 什么时候该上进阶（G10）
两条进阶路：
| 路 | 解决什么 | 贵在哪 |
|---|---|---|
| 知识图谱（GraphRAG） | "A 和 B 什么关系"这类问题 | ⭐ 贵在建（建图要调大模型抽取、work_dir ≥ 5GB、文档变了要重建） |
| CoRAG（链式检索） | 需要多跳推理才答得出的问题 | ⭐ 贵在查（max_path_length 默认 3，查询链更长更慢） |
⭐⭐ 「该不该上」的判断表里有一个一票否决项：
没把 G4 / G5 试到头（切分没调优、三个调点没试），就不要上进阶。
为什么：基础检索没调好，上进阶只是把问题掩盖得更贵。 ⚠️ 不要给读者造成"不用就是落后"的错觉 —— 进阶方案会带来很高的构建与维护成本。
可量化入口：官方 coRagEvaluator 的 enable_naive_retrieval=True 会同时输出
corag_accuracy vs naive_accuracy —— 拿自己的数据比一次，再决定。
四、块四 · 评估与容量（G7 + G8）
4.1 效果评估（G7）—— 把"感觉还行"变成"有数字"
接口：RAGEvaluator(llm, embeddings) → evaluate(metrics, dataset, language, ...)
官方给了 12 个指标（名称 / 含义 / 所需字段 / 范围 / 方向）。
4.2 ⭐⭐⭐ 这一课最重要的一句话
官方给你尺子的刻度，不给你及格线，更不给你考题。
| 官方给的 | 你要自己定的 |
|---|---|
| 指标名 / 含义 / 字段要求 / 取值范围 / 方向 | 合格线（阈值） |
| 数据集格式（四键 + 长度上限 128） | 数据集内容 |
| — | 对比基准 |
⭐ 所以评估报告里必须写死一句：
"合格线 X 为本项目自定，官方未给出阈值。"
⚠️ 一条容易被误判的现象：nv_ 系列用大模型当判官，两次跑分数会有波动 ——
这是正常的，不是系统不稳定。
4.3 容量与成本（G8）—— 要几台机器、卡怎么分
⚠️ 先划清边界：
| 谁管 | |
|---|---|
| D5 | 服务别挂 |
| F4 | 跑得快不快 |
| G8 | ⭐ 要花多少、怎么花最省（采购与业务视角） |
官方给的算法（可照抄）：
| 项 | 官方依据 |
|---|---|
| 单卡能放多少 | KV Cache Block 算法：cacheBlockSize 默认 128；maxBatchSize 有上限公式（Floor[...]） |
| 要几台机器 | 官方《大规模专家并行方案典型配置》的 A2 / A3 节点规格表（按节点规模查表，不是按模型名） |
| 自动找最优参数 | msserviceprofiler advisor / optimizer（服务化自动寻优工具） |
| 性能基准 | MindIE《性能/精度测试工具》AISBench |
命令 msserviceprofiler advisor
含义：自动给出参数建议 拆解：
advisor（给建议）／optimizer（找更优解）／train（训练调优模型） 用法：配合环境变量SERVICE_PROF_CONFIG_PATH期望：输出建议参数 不过会怎样：建议值是"参考起点"，不是"最优解" —— 还要用你的真实流量复测
命令 grep npuBlockNum <配置文件>
含义：取 Total Block Num（算 KV Cache 上限要用） 期望：拿到块数 不过会怎样：拿不到 → 回 MindIE 配置文件确认字段名（随版本变）
⚠️⚠️ 官方完全不包含任何价格数字： 只给"成本 = 吞吐 × 单价"的框架，价格要按你的采购 / 云计费来填。 本指南也不给任何价格数字。
4.4 ⚠️ 一条口径陷阱（G8 发现）
官方的性能阈值分散在不同产品、不同场景下，口径并不统一 —— 别把它们合成一张"通用红线表"。 （例：MindSpeed 那张表原文就声明不适用于在线推理、KV Cache、推理量化和服务化调度。）
五、四个块共同的坑
| # | 坑 | 症状 | 怎么办 |
|---|---|---|---|
| 1 | 只做了"私有化"的第一件事 | 以为部署在内网就安全了 | 数据流向 + 资产保护也要答 |
| 2 | 把 RAG SDK 当"全套解决方案" | 上线才发现没有权限体系 | ⭐ 官方明说不含业务级权限，要自己做 |
| 3 | 把缓存的数据库当安全存储 | 把敏感信息存进缓存库 | ⭐ 官方警告：未加密存储 |
| 4 | 接口没包 try/except | 一个异常整个进程退出 | 按官方硬规范包上 |
| 5 | upload_files 没看返回值 |
以为灌进去了，其实没有 | ⭐ 它返回的是失败列表 |
| 6 | 用官方示例的默认参数上线 | 检索效果差 | ⭐ k/score_threshold/reranker 默认都不站你这边 |
| 7 | 基础没调好就上进阶 | 花了大价钱，效果没提升 | ⭐ 一票否决：先试到 G4/G5 的头 |
| 8 | 把官方指标当及格线 | 报告里写不出"合格理由" | ⭐ 官方只给刻度，不给及格线 |
六、这一部分的位置
↑ 业务系统（你的应用）
│
│ ★ 你在 G 部分 私有化与安全 → 知识库建设 → 检索与问答 → 评估与容量
│ 基础来自：D 层（推理服务）+ L2/L1/L0
│
↓ D 层 · L3 服务层（模型怎么对外服务）
↓ A–F：技术跑通
| 关系 | 说明 |
|---|---|
| 它依赖谁 | D 层（要有能调用的推理服务）+ L0–L2 |
| 谁依赖它 | 你的业务系统 |
| 一句话定位 | A–F 是"技术能跑"，G 是"业务能用" |
⚠️ 一个还没覆盖的空白（诚实标注）： 官方四大开发场景里的「训练开发」在 A–G 里零覆盖（LLM 训练 / 微调 / 分布式训练加速）。 企业第二个常问的就是"能不能用我们自己的数据训练一下" —— 这块如果要做，是 H 层。
附 · 命令速查（复制即用）
# ── 装 RAG SDK ──
chmod u+x Ascend-mindxsdk-mxindex_<版本>_linux-aarch64.run
./<安装包>.run --check
echo y | ./<安装包>.run --install --install-path=/your/path
pip3 install -r <安装路径>/mxRag/requirements.txt
source ~/.bashrc # 三个环境变量都要 source
# ── 验装 ──
python3 -c "import mxRag; print('RAG SDK import: OK')" # 只证明能导入
pip3 list | grep mxRag
ls <embedding模型路径> # 目录要非空
# ── 端口与数据流向（安全）──
ss -lntp # 服务在听吗
ss -ntp # 在跟谁通话（有无外发）
# ── 容量与成本 ──
msserviceprofiler advisor # 参数建议
npu-smi info watch -s u # 利用率
df -h ; free -h # 资源余量
⭐ 判据速记：
- upload_files 的失败列表为空 ✓ → 文档真的进去了
- choices[0].text 非空 ✓（回 D 层）→ 服务真的能答
- 问一个只有这份文档能答的问题、答对了 ✓ → RAG 真的起作用了
- 问一个文档里完全没有的事、它答"不知道" ✓ → 它没有编
附 · 本部分的"官方素材在哪"
| 课 | 官方物 |
|---|---|
| G1 | CANN《Ras 类算子》PMCC / AVI 用户指南 / 《加固须知》 |
| G2–G4 | RAG SDK（MindSDK）《简介》《开发流程》《安装部署》《知识管理》《接口参考》 |
| G5 | RAG SDK api/retrieval.md api/reranker.md api/embedding.md |
| G6 | RAG SDK api/llm_chains.md api/cache_module.md api/prompt_compression.md api/llm_client.md |
| G7 | RAG SDK api/evaluation_module.md |
| G8 | RAG SDK api/model_inference_acceleration.md + MindIE《性能/精度测试工具》+《大规模专家并行方案典型配置》+ 服务化自动寻优工具 |
| G9 | RAG SDK《安全加固》+ MindIE《安全、认证与限流》《安全管理·日志管理》+ MindEdge《安全加固》+ AVI |
| G10 | RAG SDK api/knowledge_graph.md api/corag_module.md |
| 下载入口 | 昇腾社区 → MindStudio / MindSDK 软件下载（⚠️ 不在 CANN 下载页） |
本部分浓缩自：G1–G10 共 10 课（约 8,300 行） 上一部分：F 部分 · 场景实战 后续（未立项）：H 层 · 模型定制（训练 / 微调）