1 非商用说明

该文档提供的内容为参考实践，仅供用户参考使用，用户可参考实践文档构建自己的软件，按需进行安全、可靠性加固，但不建议直接将相关Demo或镜像文件集成到商用产品中。

2 方案介绍

2.1 背景介绍

当前业界大量开源 RAG（Retrieval-Augmented Generation）方案主要聚焦于向量检索能力建设，但在企业级复杂知识场景中普遍存在召回率不足、知识覆盖不完整、多跳关联查询能力弱等问题。当知识库规模达到百万级以上，且同时包含文档、数据库表、代码仓库、FAQ、工单、业务规则等结构化与非结构化数据时，仅依赖单一向量检索往往难以准确定位目标知识，导致大模型出现“检索不到、检索不全、检索不准”等现象，影响最终检索质量。

因此，需要构建企业级高召回混合检索方案，目标实现 RAG 召回率超过 85%。方案应支持向量检索、关键词检索、全文检索等多种检索方式融合，通过多路召回与重排序（Rerank）机制提升检索准确率。同时支持结构化数据与非结构化数据统一索引和混合查询，实现跨数据源知识关联分析。在平台集成方面，应提供标准化 API、MCP及Skill对接机制，能够灵活对接 Dify、OpenClaw等主流 Agent 平台，为企业级 AI Agent 提供高质量、高准确率的知识检索底座。

2.2 方案简介

系统采用分层架构，核心能力包括：

1. 文档解析：支持 15+ 格式、6 种解析模式（General/Pro/Expert/Deep/Fine/QA），根据复杂度平衡成本与质量，解析泛化性较业界提升 15%。
2. 检索增强：提供 Hybrid Search（关键词+向量）、Doc2Chunk Search（文档级过滤）、JSON Search（逻辑表达式+语义）三路径，复杂 PDF 场景召回率领先 40%。
3. 评估与治理：通过 Task/Trace/AccessKey 实现任务状态监控、失败重试和链路追踪，支持 7 项评估指标（如 Faithfulness、Answer Relevancy）客观量化效果。
4. 灵活集成：支持 FastAPI/MCP/Skill 三种接入方式，模型与数据库层可插拔替换（如 Embedding 模型、pgvector/Milvus 等向量库）。

3 安装部署参考实践

3.1 场景介绍

本参考实践使用容器启动方式部署RAG服务以及数据库，模型使用本地化部署。

3.2 环境信息说明

本参考实践所使用的软硬件信息如下表所示。

表1 软件信息

表2 Witty RAG（含向量数据库）硬件规格

表3 LLM+Embedding+Rerank模型配置（Witty RAG服务依赖）

3.3 部署指南

本参考实践提供docker部署及openFuyao(k8s)的helm chart部署两种实践，两者使用的运行时有差异，不建议同时使用。

3.3.1 docker部署

3.3.1.1 安装docker

步骤1   安装 docker-engine，以参考实践使用的openEuler 24.03为例：

sudo yum install -y docker-engine

步骤2    启动 Docker 守护进程。

sudo systemctl enable docker --now

步骤3    验证安装。

docker --version

步骤4    配置镜像加速源。

编辑 /etc/docker/daemon.json（如不存在则创建）：

{"registry-mirrors":["https://docker.m.daocloud.io","https://docker.1panel.live","https://hub.rat.dev","https://
docker.mirrors.ustc.edu.cn","https://dockerpull.com"]}

步骤5    配置后重启 Docker。

sudo systemctl daemon-reload 
sudo systemctl restart docker

           ----结束

3.3.1.2 镜像获取

本方案涉及rag服务的应用镜像以及openGauss数据库的镜像，openGuass数据库镜像直接拉取，rag服务应用镜像通过dockerfile构建。

步骤1    拉取euler-copilot-rag源码，用于镜像构建及后续配置文件配置。

GIT_LFS_SKIP_SMUDGE=1 git clone https://atomgit.com/openeuler/euler-copilot-rag.git -b release-0.10.2 后续更新为版
本正式分支

步骤2    拉取openGauss数据库镜像。

docker pull hub-harbor.oepkgs.net/neocopilot/
opengauss@sha256:38a63d58b2b41e3668cde9f9588a74cb4e8aee76b301f7feb86d6a49d871f10c  # ARM64 架构

步骤3    构建rag服务应用镜像。

源码包中有一键构建镜像的脚本，可以直接执行，脚本会按照dockerfile拉取对应的依赖并构建镜像。

cd /home/euler-copilot-rag
# 构建基础镜像 + 应用镜像
bash rag_core/deploy/build.sh

           ----结束

3.3.1.3 启动容器

步骤1     配置对应的config.toml文件，在euler-copilot-rag/rag_core目录下新建config.toml文件。

vim /home/euler-copilot-rag/rag_core/config.toml

将下面内容复制到config.toml文件并保存，按照实际需要修改使用的标量数据库，向量数据库以及对应的端口号，模型model_name ,api_key, end_point等信息。

[static_source]
aes_key="34b7cfdcd1d47fc3d11c784c6e981705" # 自定义
stop_words_path = "./rag_core/static/stopwords.txt"
[service]
is_debug = false
uvicorn_ip = "0.0.0.0"
uvicorn_port = 9988
ssl_enable = false
log_level = "INFO"
[scalar_db]
database_type = "opengauss"      # milvus | opengauss | postgres
database_host = "opengauss"
database_port = 5432
database_user = "gaussdb"
database_password = "Admin@123456" # 默认密码，后续按需修改
database_db = "postgres"
database_pool_size = 10
[vector_db]
database_type = "opengauss"      # milvus | opengauss | postgres
database_host = "opengauss"
database_port = 5432
database_user = "gaussdb"
database_password = "Admin@123456" # 默认密码，后续按需修改
database_db = "postgres"
database_pool_size = 10
[graph_db]
[task]
task_retry_time = 3
cpu_limit = 32 #文档解析任务的最大并发数，按需修改
[chat_model]
model_name = "qwen3-32b"
online_status = "online"
model_labels = ["txt2txt",]
model_provider = "openai"
end_point = "https://192.168.9.138:8009/v1"
api_key = ""
request_timeout = 60
input_max_tokens = 65536
output_max_tokens = 65536
temperature = 0.7
batch_size = 16
[embedding_model]
model_name = "Qwen3-VL-Embedding-8B" # 具体为本地部署时候定义的模型名称
online_status = "online"
model_labels = ["txt2embedding"]
model_provider = "openai"
end_point = "http://192.168.9.138:8010/v1/embeddings"
api_key = ""
request_timeout = 60
input_max_tokens = 8192
output_max_tokens = 8192
temperature = 0.7
batch_size = 16
[rerank_model]
model_name = "Qwen3-VL-Reranker-8B" # 具体为本地部署时候定义的模型名称
online_status = "online"
model_labels = ["reranker"]
model_provider = "openai"
end_point = "http://192.168.9.138:8011/v1/rerank"
api_key = ""
request_timeout = 60
input_max_tokens = 8192
output_max_tokens = 8192
temperature = 0.7
batch_size = 16
[ocr_model]
[voice_to_text_model]

[video_to_text_model]

步骤2    自定义docker网络。

docker network create witty-rag-net

步骤3    启动openGauss容器。

源码包中有一键构建镜像的脚本，可以直接执行，脚本会按照dockerfile拉取对应的依赖并构建镜像。

docker run -d \
  --name opengauss \
  --network witty-rag-net \
  --restart unless-stopped \
  -p 5434:5432 \
  -e GS_PASSWORD=Admin@123456 \
  hub-harbor.oepkgs.net/neocopilot/
opengauss@sha256:38a63d58b2b41e3668cde9f9588a74cb4e8aee76b301f7feb86d6a49d871f10c

步骤4    openGauss 默认行为会将空字符串 ('') 存储为 NULL，这会导致应用层读取时出现None。启动openGuass的容器后需要在数据库中修改 behavior_compat_options 参数。

# 进入 openGauss 容器
docker exec -it opengauss bash
# 修改参数并生效（切换到 omm 用户执行）
su - omm
gs_guc reload -D /var/lib/opengauss/data -c "behavior_compat_options='accept_empty_str'"

accept_empty_str 参数确保空字符串在数据库中仍以空字符串形式存储，不会被转为NULL，避免应用层出现空值异常。

步骤5    启动rag-core容器，-v 参数使用的映射目录可以按照实际填写。

docker run -d \
  --name witty-rag-core \
  --network witty-rag-net \
  -p 9988:9988 \
  -e RAG_WORKERS=4 \
  -v /home/euler-copilot-rag/rag_core/config.toml:/rag-service/rag_core/config.toml \
  -v /opt/witty-rag/logs:/rag-service/logs \
  witty-rag-core:0.1.0

步骤6    验证服务是否启动成功。

docker exec witty-rag-core curl -s http://127.0.0.1:9988/health_check

如果服务启动成功该指令会返回OK，后续继续按照章节4"端到端使用指导"进行下一步验证及使用。若不成功则使用docker logs 检查相关的容器日志。

        ----结束

3.3.2 openFuyao平台部署

openFuyao社区致力于构建面向多样化算力集群的开放软件生态，专注于推动云原生与AI原生技术的高效协同，促进有效算力的极致释放。社区发行版以模块化、轻量化、安全可靠为核心设计理念，基于开源的Kubernetes平台深度优化，提供开箱即用的容器化集群管理能力，涵盖资源编排、弹性伸缩、多维度监控等基础功能，满足企业级生产环境的运维需求。具体的部署方式参考算力底座参考实践2.2章节“安装部署”。

3.3.2.1 镜像获取与推送

步骤1    获取镜像。

获取openGauss镜像。

ctr -n k8s.io images pull hub-harbor.oepkgs.net/neocopilot/
opengauss@sha256:38a63d58b2b41e3668cde9f9588a74cb4e8aee76b301f7feb86d6a49d871f10c

获取witty-rag-core镜像，参考3.3.1.3章节"镜像获取"构建witty-rag-core镜像。
镜像无论是本地通过脚本构建或者其他服务器上面导入后导出都可以使用以下方式：

docker save witty-rag-core:0.1.0 witty-rag-core-base:0.1.0 -o witty-rag-core-0.1.0-arm64.tar #导出
ctr -n k8s.io images import witty-rag-core-0.1.0-arm64.tar #导入

步骤2   给镜像打标签，根据自身的harbor仓库情况修改标签。

ctr -n k8s.io image tag docker.io/library/witty-rag-core:0.1.0 deploy.bocloud.k8s:40443/kubernetes/docker.io/
library/witty-rag-core:0.1.0
ctr -n k8s.io image tag hub-harbor.oepkgs.net/neocopilot/
opengauss@sha256:38a63d58b2b41e3668cde9f9588a74cb4e8aee76b301f7feb86d6a49d871f10c 
deploy.bocloud.k8s:40443/kubernetes/hub-harbor.oepkgs.net/neocopilot/opengauss:7.0.0-RC3

步骤3    推送镜像，推送地址需要改成对应的harbor仓库的地址。

ctr -n k8s.io images push --platform linux/arm64 --skip-verify --local deploy.bocloud.k8s:40443/kubernetes/
hub-harbor.oepkgs.net/neocopilot/opengauss:7.0.0-RC3
ctr -n k8s.io images push --platform linux/arm64 --skip-verify --local deploy.bocloud.k8s:40443/kubernetes/
docker.io/library/witty-rag-core:0.1.0

步骤4    查看harbor空间验证镜像推送成功，可以在后面使用grep搜索对应的镜像名称。

curl -s -k https://deploy.bocloud.k8s:40443/v2/_catalog | jq -r '.repositories[]' | while read repo; do tags=$
(curl -s -k https://deploy.bocloud.k8s:40443/v2/$repo/tags/list | jq -r '.tags[]?'); for tag in $tags; do echo 
e "$repo \t $tag"; done; done | column -t

           ----结束

3.3.2.2 创建helm chart应用

源代码helm_chart目录结构图如下：

3.3.2.2.1 创建openGauss应用

步骤1    获取helm chart文件。

cd /home
GIT_LFS_SKIP_SMUDGE=1 git clone https://atomgit.com/openeuler/euler-copilot-rag.git -b release-0.10.2

步骤2    创建命名空间。

kubectl create ns witty-rag-ns

步骤3    按照仓库镜像的名称跟标签修改helm_chart的values.yaml文件。

vim /home/euler-copilot-rag/helm_chart/witty-opengauss/values.yaml

步骤4    按照实际修改刚才helm_chart的values.yaml文件中数据库对应的端口号，账号密码等信息。

步骤5    安装openGauss应用。

cd /home/euler-copilot-rag/helm_chart
helm install witty-opengauss ./witty-opengauss -n witty-rag-ns

步骤6    查看应用pod状态以及日志。

# 查看应用pod状态
kubectl get pod  -n witty-rag-ns
# 查询特定pod日志
kubectl logs witty-opengauss-434c4c8979-q5v6g -n witty-rag-ns

           ----结束

3.3.2.2.2 创建witty-rag-core应用

步骤1    进入之前的helm_chart源码目录。

cd /home/euler-copilot-rag/helm_chart

步骤2    按照仓库镜像的名称跟标签修改helm_chart的values.yaml文件。

vim /home/euler-copilot-rag/helm_chart/witty-rag-core/values.yaml

步骤3    按照实际修改刚才helm_chart的values.yaml文件中使用的标量数据库，向量数据库以及对应的端口号，账号密码，模型model_name ,api_key, end_point等信息。

步骤4    安装rag应用, 命名空间使用之前创建好的witty-rag-ns。

helm install witty-rag-core ./witty-rag-core -n witty-rag-ns

步骤5    查看应用pod状态以及日志。

# 查看应用pod状态
kubectl get pod  -n witty-rag-ns
# 查询特定pod日志
kubectl logs witty-rag-core-574c4c8979-q5v6g -n witty-rag-ns

若pod正常运行且日志无异常，后续继续按照章节4"端到端使用指导"进行下一步验证及使用。

           ----结束

注意：Helm Chart 文件中的 values 配置包含账号与密码信息，若在生产环境中使用，建议采用加密或外部密钥管理方式保护敏感信息，避免密码泄露风险。

4 端到端使用指导

以下是端到端使用的流程图：

4.1 模型配置及服务启动

该章节用于演示Witty RAG服务模型的配置与修改，以docker部署为例。若在3.3部署指南章节已经完成模型的配置，则可以跳过。

步骤1    编辑config.toml文件，修改使用的模型。

以euler-copilot-rag位于/home目录为例，具体以git clone时候下载的目录为准。

vim /home/euler-copilot-rag/rag_core/config.toml

步骤2    按照部署的模型修改chat_model,embedding_model,rerank_model等配置，还可以按需配置ocr_model、voice_model等。

主要修改model_name, model_provider,end_point,api_key即可。

对于LLM模型，默认为多模态，若非多模态模型则需要将model_labels的"img2txt"标签去掉。

步骤3    重启服务。

docker restart witty-rag-core opengauss

若容器尚未启动，则参考章节3.3.4 "启动容器" 进行容器的启动。

           ----结束

4.2 知识库的创建与查看

步骤1    创建知识库，设置知识库的名称跟access_key。

此处-H "Authorization: Bearer后自定义知识库的access_key，后续知识库的查看，文档的上传查看等操作均使用自定义的acess_key进行校验。

curl -X POST http://localhost:9988/kb \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer 34b7cfdcd1d47fc3d11c784c6e981705" \
  -d '{
    "name": "test-doc-kb2",
    "description": "Test knowledge base",
    "meta_data_type": "document",
     }'

步骤2   查看已创建的知识库。

根据步骤1接口返回的kb_id查看知识库。

curl "http://localhost:9988/kb/cfa53c68-689d-4eb1-a614-8c9ec22fe810" -H "Authorization: Bearer 
34b7cfdcd1d47fc3d11c784c6e981705"

创建知识库的时候可以设置对应的模型id调用对应的模型，若不设置则默认使用config.toml文件配置的模型。

           ----结束

4.3 文档导入与查看

步骤1    批量导入文档。

根据4.2知识库的创建与查看获取接口返回的kb_id并设置。

vim /home/euler-copilot-rag/rag_core/config.toml

调用接口批量导入文档, 要导入多个文档则追加-F参数， doc_files=@后面改成文档所在的路径。

curl -X POST "http://localhost:9988/doc/${KB_ID}"   -H "Authorization: Bearer 
34b7cfdcd1d47fc3d11c784c6e981705"   -F "doc_files=@/home/cjy/中国甲状腺癌规范诊疗质量控制指标(2022
版)_1.pdf"   -F "doc_files=@/home/cjy/FAK抑制抗原处理和呈 递以促进胰腺癌的免疫逃避。_14.pdf"

接口返回文档的id，后续用于查看文档信息。

步骤2   查看导入的文档，doc/后面替换成刚刚返回的文档的id进行查看。

curl "http://localhost:9988/doc/01159e74-1c66-460b-a88f-4ab137edbcb1" \
  -H "Authorization: Bearer 34b7cfdcd1d47fc3d11c784c6e981705"

接口会返回文档的信息、片段以及向量化后的文档内容。

           ----结束

4.4 获取检索片段

步骤1    调用接口获取检索片段。

以euler-copilot-rag位于/home目录为例，具体以git clone时候下载的目录为准。

curl -X POST http://localhost:9988/chunk/search \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer 34b7cfdcd1d47fc3d11c784c6e981705" \
  -d "{
\"search_chunk_configs\": [{
      \"kb_id\": \"cfa53c68-689d-4eb1-a614-8c9ec22fe810\",
      \"query\": \"甲状腺癌全切术后甲状旁腺功能评估率\",
      \"top_k\": 5,
      \"search_method\": \"hybrid_search\"
    }]
  }"

接口返回topk个检索出来的片段，默认k=5。

           ----结束

5 功能特性说明

5.1 Witty RAG对接方式

5.1.1 使用Skill接入

步骤1    启动agent平台，本参考实践以OpenClaw为例，OpenClaw部署参考以下文档：部署指南

拉取镜像。

docker pull swr.cn-north-4.myhuaweicloud.com/kunpeng-ai/openclaw-openviking:latest 

启动服务， 容器需要接入自定义的网络witty-rag-net。

下面的启动示例启动了一个名称为"oc-ov"的容器。

docker run -d --name oc-ov --network witty-rag-net -p 18789:18789 -p 1933:1933 \  
-e OPENVIKING_ARK_API_KEY="使用自己的API Key" \   
-e OPENCLAW_DEFAULT_MODEL="volcengine/doubao-seed-1-8-251228" \ 
-e OPENCLAW_GATEWAY_TOKEN="my-secret-password-123" \  
-e VOLCANO_ENGINE_API_KEY="使用自己的API Key" \   
swr.cn-north-4.myhuaweicloud.com/kunpeng-ai/openclaw-openviking:latest

步骤2   进入容器"oc-ov"启动openclaw TUI进行交互。

docker exec -it oc-ov openclaw tui

步骤3    导入skill。

拉取源代码并将源代码目录下的agent目录拷贝到容器中, 若在上文步骤已经拉取则不需要重复拉取。

cd /home
git clone https://atomgit.com/openeuler/euler-copilot-rag.git
docker cp /home/euler-copilot-rag/rag_core/agent oc-ov:/home/agent

使用自然语言向openclaw描述检视对应的文件夹，并加载skill。

请检索我的/home/agent的文件夹，里面有skill.md以及一些skill相关的，整理并识别出里面的skill，加载到你的
skill列表里面去。

后续可以使用自然语言描述查看openclaw拥有的技能，以及进行知识库创建，文档上传，检索等操作。

步骤4   创建知识库。

我要使用创建知识库的技能，请帮我创建一个openclaw-test-kb的知识库。

步骤5    导入文档。

帮我导入/home目录下的两个pdf文档到刚刚创建的知识库。

步骤6    查看文档解析状态。

请帮我查询刚才上传的文档的解析状态。

步骤7     查询上传的文档。

帮我查询中国开头的那篇文档的详情。

步骤8     获取检索片段。

帮我进行检索，关键字是甲状腺癌全切术后甲状旁腺功能评估率，返回top k=3的片段即可。

          ----结束

5.1.2 使用FastAPI接入

请参考章节4端到端使用指导中的API调用示例进行使用。
若使用Agent平台接入，以OpenClaw为例，使用自然语言让agent进行请求的发送与返回。OpenClaw的部署请参考章节5.1.1 步骤1部分。
可以直接让agent执行对应的接口请求以及结果返回：

或者让agent查看API说明文档，进行接口的调用：

5.1.3 使用MCP接入

步骤1    参考5.1.1 使用Skill接入的步骤1完成镜像的拉取以及容器的启动，注意OpenClaw容器需要跟RAG服务容器，RAG服务使用的数据库容器等在同一个网络。

步骤2   拉取rag服务源代码并拷贝到 oc-ov 容器, 若在上文步骤已经拉取则不需要重复拉取。

cd /home
GIT_LFS_SKIP_SMUDGE=1 git clone https://atomgit.com/openeuler/euler-copilot-rag.git -b release-0.10.2  后续更新为版
本正式分支
docker cp /home/euler-copilot-rag oc-ov:/home/euler-copilot-rag

步骤3    安装 MCP 插件并启用。

docker exec oc-ov openclaw plugins install /home/euler-copilot-rag/rag_core/agent/rag_core_mcp
#若安装插件后容器停止，则使用docker restart oc-ov先进行重启，后续应用插件后还是需要一次重启。
docker exec oc-ov openclaw plugins enable mcp-services

步骤4   重启 oc-ov 容器应用插件。

docker restart oc-ov

步骤5    在 witty-rag-core 容器内安装 mcp 依赖（首次部署MCP才需要）。

docker exec witty-rag-core pip install mcp APScheduler pyyaml
docker exec witty-rag-core pip install 'fastapi>=0.115.0' 'starlette>=0.49.1'

步骤6    拷入 euler-copilot-rag 代码到 witty-rag-core 容器（首次部署MCP才需要）。

docker cp /home/euler-copilot-rag witty-rag-core:/rag-service/euler-copilot-rag

步骤7     拷入 rag_core 配置文件（首次部署MCP才需要）。

# MCP server.py 启动时 bootstrap 会读取 rag_core/config.toml
docker exec witty-rag-core bash -c "cp /rag-service/rag_core/config.toml /rag-service/euler-copilot-rag/
rag_core/config.toml"

步骤8     在容器内启动 MCP SSE 服务（witty-rag-core 重启后需重新执行）。

docker exec -d witty-rag-core bash -c "cd /rag-service/euler-copilot-rag/rag_core/agent/rag_core_mcp && 
RAG_CORE_BASE_URL=http://127.0.0.1:9988 RAG_CORE_MCP_PORT=12312 python3 server.py >> /tmp/
mcp.log 2>&1"

步骤9    更新 oc-ov 的 mcp_config.json 地址, 因为源代码的地址适用于多场景，目前为docker场景，将地址改成容器名。

docker exec oc-ov sed -i 's|http://localhost:12312/sse|http://witty-rag-core:12312/sse|g' /root/.openclaw/
extensions/mcp-services/mcp_config.json

步骤10    重启 oc-ov 并验证。

docker restart oc-ov
sleep 15
docker ps --filter name=oc-ov --format '{{.Status}}\t{{.Ports}}'
docker logs oc-ov --tail 20 2>&1 | grep -E "(initialize|Discovered|tool|MCP|rag|register|listening|started)"

日志输出示例如下：

步骤11     测试验证MCP功能。

检查当前的MCP服务：

创建知识库：

导入文档：

查询文档解析状态：

查询文档详情：

获取检索片段：

          ----结束

5.2 Witty RAG兼容支持Milvus

5.2.1 配置指导

Witty RAG支持对接向量数据库Milvus，以下是docker部署与openFuyao平台部署两种方式下对接Milvus的参考。

5.2.1.1 docker部署

步骤1    拉取milvus, etcd,minio等镜像。

docker pull milvusdb/milvus:v2.6.17
docker pull bitnami/etcd:3.5.16
docker pull minio/minio:RELEASE.2025-04-22T22-12-26Z

注意：这里使用的milvus版本需要>=2.6.9

步骤2   清理旧环境 (自动忽略删除不存在容器的报错)。

docker rm -f milvus-standalone milvus-etcd milvus-minio 2>/dev/null
mkdir -p /opt/milvus/volumes/{etcd,minio,milvus}

步骤3     创建专用网络, 若之前的步骤中已经创建则忽略。

docker network create witty-rag-net 2>/dev/null || true

步骤4    赋予etcd目录权限。

chown -R 1001:1001 /opt/milvus/volumes/etcd

步骤5    启动ectd容器。

docker run -d \
  --name milvus-etcd \
  --network witty-rag-net \
  -v /opt/milvus/volumes/etcd:/bitnami/etcd \
  -e ETCD_DATA_DIR=/bitnami/etcd \
  -e ALLOW_NONE_AUTHENTICATION=yes \
  bitnami/etcd:3.5.16

步骤6   启动minio容器。

docker run -d \
  --name milvus-minio \
  --network witty-rag-net \
  -e MINIO_ROOT_USER=minioadmin \
  -e MINIO_ROOT_PASSWORD=minioadmin \
  -v /opt/milvus/volumes/minio:/minio_data \
  minio/minio:RELEASE.2025-04-22T22-12-26Z server /minio_data

步骤7     启动milvus容器。

docker run -d \
  --name milvus-standalone \
  --network witty-rag-net \
  -p 19530:19530 \
  -p 9091:9091 \
  -e ETCD_ENDPOINTS=milvus-etcd:2379 \
  -e MINIO_ADDRESS=milvus-minio:9000 \
  -e MINIO_ROOT_USER=minioadmin \
  -e MINIO_ROOT_PASSWORD=minioadmin   \
  -v /opt/milvus/volumes/milvus:/var/lib/milvus \
  --security-opt seccomp=unconfined \
  milvusdb/milvus:v2.4.18 milvus run standalone

步骤8     执行健康检查，检查milvus是否正常启动并且正常连接minio,etcd。

curl http://localhost:9091/healthz

步骤9    修改config.toml文件，将向量数据库改成milvus并且重启witty-rag-core容器。

milvus数据库未设置认证方式，对应字段留空即可，也可以按实际情况进行修改。

重启witty-rag-core容器。

docker restart witty-rag-core

          ----结束

5.2.1.2 openFuyao平台部署

步骤1     拉取milvus,minio,etcd镜像。

ctr -n k8s.io images pull milvusdb/milvus:v2.6.17
ctr -n k8s.io images pull bitnami/etcd:3.5.16
ctr -n k8s.io images pull minio/minio:RELEASE.2025-04-22T22-12-26Z

步骤2   给镜像打标签，根据自身的harbor仓库情况修改标签。

ctr -n k8s.io image tag milvusdb/milvus:v2.6.17 deploy.bocloud.k8s:40443/kubernetes/milvusdb/
milvus:v2.6.17
ctr -n k8s.io image tag bitnami/etcd:3.5.16 deploy.bocloud.k8s:40443/kubernetes/bitnami/etcd:3.5.16
ctr -n k8s.io image tag minio/minio:RELEASE.2025-04-22T22-12-26Z deploy.bocloud.k8s:40443/kubernetes/
minio/minio:RELEASE.2025-04-22T22-12-26Z

步骤3     推送镜像，推送地址需要改成对应的harbor仓库的地址。

ctr -n k8s.io images push --platform linux/arm64 --skip-verify --local deploy.bocloud.k8s:40443/kubernetes/
milvusdb/milvus:v2.6.17
ctr -n k8s.io images push --platform linux/arm64 --skip-verify --local deploy.bocloud.k8s:40443/kubernetes/
bitnami/etcd:3.5.16
ctr -n k8s.io images push --platform linux/arm64 --skip-verify --local deploy.bocloud.k8s:40443/kubernetes/
minio/minio:RELEASE.2025-04-22T22-12-26Z

步骤4    获取helm chart文件，若在上面步骤已经拉取请忽略。

cd /home
GIT_LFS_SKIP_SMUDGE=1 git clone https://atomgit.com/jianyang_chen/euler-copilot-rag_all_branch -b release-0.10.2

步骤5    按照仓库镜像的名称跟标签修改helm_chart的values.yaml文件。

vim /home/euler-copilot-rag/helm_chart/witty-milvus/values.yaml

步骤6   安装milvus应用, 命名空间使用rag服务pod所在的命名空间。

cd /home/euler-copilot-rag/helm_chart
helm install witty-milvus ./witty-milvus -n witty-rag-n

步骤7     查看witty-milvus应用pod状态以及日志。

# 查看应用pod状态
kubectl get pod  -n witty-rag-ns
# 查询特定pod日志
kubectl logs witty-milvus-574c4c8979-q5v6g -n witty-rag-ns

步骤8     修改witty-rag-core应用对接的模型，更新应用。

vim /home/euler-copilot-rag/helm_chart/witty-rag-core/values.yaml

将向量数据库修改为Milvus，并且修改对应的数据库端口号以及账号密码。

步骤9    更新应用，并参考步骤7检查witty-rag-core应用pod的状态。

cd /home/euler-copilot-rag/helm_chart
helm upgrade witty-rag-core ./witty-rag-core -n witty-rag-ns

检查配置正确写入并更新：

kubectl exec -n_witty-rag-ns witty-rag-core-6488bb7fc8-zkld5 -- cat /rag-service/rag_core/config.toml 2>&1 
I grep  -A5 "\[vector_db\]"

        ----结束

注意：Helm Chart 文件中的 values 配置包含账号与密码信息，若在生产环境中使用，建议采用加密或外部密钥管理方式保护敏感信息，避免密码泄露风险。

5.2.2 鲲鹏BoostKit加速向量数据库Milvus

鲲鹏BoostKit加速库对于向量数据库Milvus开发了一些特性支持如鲲鹏KBest索引算法，鲲鹏KScaNN算法，通过使能这些特性，能达到提升Milvus数据库性能的效果。

以下示例是在物理机环境执行的示例，这两个优化特性使能也可以在容器中执行，或者使能后打包成镜像供容器使用。

5.2.2.1 环境信息说明

表1 硬件信息

表2 软件信息

5.2.2.2 Milvus KBest优化

5.2.2.2.1 简介与约束

简介：在Milvus支持的所有索引算法中，基于图的索引算法是HNSW（Hierarchical Navigable Small World），它能进行快速查询，取得较高的召回率，但是消耗的内存资源较大。为了扩展基于图的索引算法，在保证高召回率的前提下，尽可能加速查询效率，鲲鹏BoostKit提出了KBest（Kunpeng Blazing-fast embedding similarity search thruster）鲲鹏图检索算法。KBest是鲲鹏自研的高效的图索引算法，通过量化、向量指令等方法优化了最近邻搜索的性能和精度，提供了对标开源Faiss HNSW算法的检索能力。

本特性以patch文件的方式实现，将KBest算法接入开源的Milvus数据库中，无缝使用新的图索引算法。

约束：该优化用于替换HNSW索引算法的场景。

支持的参数：

5.2.2.2.2 算法库安装

步骤1    下载鲲鹏召回算法库放在主目录（~）下，解压并安装。

获取路径请参见5.2.2.1环境信息说明 表2的BoostKit-SRA_Recall-1.2.0.zip获取路径，执行以下命令解压和安装。

cd ~
unzip BoostKit-SRA_Recall-1.2.0.zip
rpm -ivh boostkit-sra_recall-1.2.0-1.aarch64.rpm

          ----结束

5.2.2.2.3 milvus源码获取及补丁应用

步骤1    使用git克隆Milvus并切换到2.4.5版本，放在主目录（~）下。

获取路径请参见5.2.2.1环境信息说明 表2，参见《Milvus 安装指南》先完成一次Milvus的编译。

git clone https://gitee.com/milvus-io/milvus.git
cd milvus
# 查看所有标签，确认 v2.4.5 是否存在, 若返回v2.4.5则为存在
git tag -l "v2.4.5" 
# 如果存在，直接切换
git checkout v2.4.5

步骤2   获取优化特性的补丁文件，将其上传到主目录（~）下。

获取路径请参见5.2.2.1环境信息说明 表2。

步骤3   合入补丁。

cd ~/milvus
git apply --whitespace=nowarn < ~/0001-milvus-add-kbest-kscann.patch
cd ~/milvus/cmake_build/thirdparty/knowhere/knowhere-src/
git apply --whitespace=nowarn < ~/0001-knowhere-add-kbest-kscann.patch

合入补丁后可以使用git status检查补丁是否打上。

           ----结束

注意：在步骤1编译Milvus的时候有可能会存在组件冲突，通常会在internal/core/conanfile.py明确thrift组件使用的版本来解决，"0001-milvus-add-kbestkscann.patch"补丁中也包含对该文件的修改以及明确thrift组件这一项，在应用补丁时要注意有可能自身代码修改与补丁代码冲突导致补丁应用失败，最好回退该文件中对于thrift组件使用的版本的修改，直接应用补丁的改动。

5.2.2.2.4 编译milvus及验证

步骤1    进入milvus目录 执行编译。

cd ~/milvus
make milvus

步骤2   验证kbest及kscann索引已编译进milvus。

nm -C /home/cjy/rp3/milvus-optimize/milvus/internal/core/output/lib64/libknowhere.so | grep -i "kbest\|
kscann"

返回包含Kbest及Kscann则编译成功。

           ----结束

5.2.2.2.5 适配应用

步骤1    修改应用源码包的配置文件。

vim /home/euler-copilot-rag/rag_core/database/db_vector/milvus/engine.py

步骤2   将所有index_type="HNSWw"改为index_type="KBEST"，参数也需要调整:

#原来HNSW:index_type="HNSW"
params={"M":32, "efConstruction": 200},
#改为 KBEST:index_type="KBEST"
params={"R":50,100, "build_index_type": "SSG"}

步骤3   修改源码后重新打包镜像，启动容器，参考3.3.1.2镜像获取章节以及3.3.1.3启动容器章节。

           ----结束

5.2.2.3 Milvus KScaNN优化

5.2.2.3.1 简介与约束

简介：Milvus数据库支持ScaNN索引算法。ScaNN（Scalable Nearest Neighbors）是由Google发布的高效向量相似性检索开源算法库，基于IVFPQ原理，通过x86上的4bit SIMD深度优化和各向异性量化损失函数优化，实现了极高的检索性能。然而，由于鲲鹏芯片的架构差异，ScaNN算法的软硬件协同优势在鲲鹏服务器上无法完全发挥，因此推出KScaNN优化特性，用于优化ScaNN类算法在鲲鹏服务器上的性能表现。KScaNN（Kunpeng Scalable Nearest Neighbors）是一种基于倒排索引，并针对鲲鹏芯片架构进行了深度优化索引布局、算法流程和计算流程的向量检索算法，旨在充分利用芯片潜力。KScaNN接口基于ScaNN开源接口进行了扩展及修改，提供了与开源ScaNN相当的完整检索能力。

此功能以patch文件的形式实现，将KScaNN算法集成到开源的Milvus数据库中，以实现对新的图索引算法的无缝支持。

约束：该优化用于替换ScaNN索引算法的场景

支持的参数：

5.3.2.3.2 算法库及KScaNN依赖安装

步骤1    下载鲲鹏召回算法库放在主目录（~）下，解压并安装。

获取路径请参见5.2.2.1环境信息说明 表2的KScaNN获取路径，执行以下命令解压和安装。

cd ~
unzip BoostKit-SRA_Recall-1.2.0.zip
rpm -ivh boostkit-sra_recall-1.2.0-1.aarch64.rpm

步骤2   下载鲲鹏系统库放在主目录（~）下，解压并安装。

获取路径请参见5.2.2.1环境信息说明 表2的KSL获取路径，执行以下命令解压和安装。

cd ~
unzip BoostKit-ksl_2.4.0.zip
rpm -ivh boostkit-ksl-2.4.0-1.aarch64.rpm

           ----结束

5.3.2.3.3 milvus源码获取及补丁应用

参考5.2.2.2.3章节"milvus源码获取及补丁应用" 部分。

5.3.2.3.4 编译KScaNN的动态库文件

步骤1    安装编译所需依赖包。

yum install python python3-pip python3-devel java-11-openjdk java-11-openjdk-devel rsync libomp hdf5 
hdf5-devel gtest-devel libuuid-devel
yum install gcc-toolset-12*

步骤2   编译安装编译软件bazel-5.3.0。

cd ~
wget https://github.com/bazelbuild/bazel/releases/download/5.3.0/bazel-5.3.0-dist.zip --no-check-certificate
unzip bazel-5.3.0-dist.zip -d bazel-5.3.0
cd bazel-5.3.0
env EXTRA_BAZEL_ARGS="--tool_java_runtime_version=local_jdk" bash ./compile.sh
export PATH=~/bazel-5.3.0/output:$PATH

步骤3   编译OpenScann的动态库文件libscann_cc.so。

设置环境变量 使用gcc12进行编译。

export PATH=/opt/openEuler/gcc-toolset-12/root/usr/bin/:$PATH
export LD_LIBRARY_PATH=/opt/openEuler/gcc-toolset-12/root/usr/lib64/:$LD_LIBRARY_PATH

下载OpenScann源码。

cd ~
wget https://gitee.com/openeuler/sra_scann_adapter/repository/archive/v1.1.0.zip --no-check-certificate 
unzip v1.1.0.zip -d OpenScann
cd OpenScann/sra_scann_adapter-v1.1.0

激活Python虚拟环境之后，编译libscann_cc.so。

conda activate milvus
sh project.sh -ag #鲲鹏920新型号使用-ag参数, 鲲鹏920使用-ah参数

           ----结束

5.3.2.3.5 编译milvus

步骤1     回退gcc版本，使用默认的gcc 10.3.1进行编译。

# 撤销 PATH（去掉 gcc12 那一段）
export PATH=$(echo "$PATH" | sed 's|/opt/openEuler/gcc-toolset-12/root/usr/bin:||g')
# 撤销 LD_LIBRARY_PATH
export LD_LIBRARY_PATH=$(echo "$LD_LIBRARY_PATH" | sed 's|/opt/openEuler/gcc-toolset-12/root/usr/
lib64/:||g')

或者使用重新打开新终端的方式回退到默认的gcc。

步骤2   安装依赖软件eigen-3.3.7。

git clone https://gitlab.com/libeigen/eigen.git
cd eigen
git checkout 33d0937c6bdf5ec999939fb17f2a553183d14a74
mkdir build && cd build
cmake .. -DCMAKE_INSTALL_PREFIX=/usr/local/eigen-3.3.7
make -sj && make install

步骤3   激活Python虚拟环境，安装Python依赖。

conda activate milvus
pip install treelite==4.2.1
pip install tl2cgen
conda install pybind11

步骤4   编译milvus。

cd ~/milvus
make milvus

步骤5   验证kbest及kscann索引已编译进milvus。

nm -C /home/cjy/rp3/milvus-optimize/milvus/internal/core/output/lib64/libknowhere.so | grep -i "kbest\|
kscann"

返回包含Kbest及Kscann则编译成功。

           ----结束

5.3.2.3.6 适配应用

步骤1     修改应用源码包的配置文件。

vim /home/euler-copilot-rag/rag_core/database/db_vector/milvus/engine.py

步骤2   若默认使用的索引为HNSW, 则推荐使用KBest优化， KScaNN优化适用于原来使用ScaNN索引的场景。

index_type="KSCANN"
#其余参数配置见说明中KScaNN支持的参数，按照实际业务需求进行配置

步骤3   修改源码后重新打包镜像，启动容器，参考3.3.1.2镜像获取章节以及3.3.1.3启动容器章节。

           ----结束

5.3.2.3.7 常见报错及解决

问题1：在编译milvus的时候报错"ERROR: Invalid setting '10.3.1' is not a valid'settings.compiler.version' value."。

原因：编译milvus组件的时候会使用conan组件拉取第三方组件，openEuler 22.03LTS SP4的操作系统默认gcc版本为10.3.1不在conan组件的默认配置文件配置gcc列表


 里，因此报错。

解决方案：在/root/.conan/settings.yml文件中，将10.3.1版本加到gcc: version列表。

5.3 Witty RAG混合检索方案

FastAPI设置混合检索：

在调用接口的时候设置search_method="hybrid_search"。

curl -X POST http://localhost:9988/chunk/search \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer 34b7cfdcd1d47fc3d11c784c6e981705" \
  -d "{

      \"search_chunk_configs\": [{
      \"kb_id\": \"cfa53c68-689d-4eb1-a614-8c9ec22fe810\",
      \"query\": \"甲状腺癌全切术后甲状旁腺功能评估率\",
      \"top_k\": 5,
      \"search_method\": \"hybrid_search\"
    }]
  }"

Skill接入设置混合检索：

在与agent交互的时候，使用自然语言说明使用混合检索的方式。