Nexent 平台集成 ModelEngine 数据工程与模型工程完整指南
Nexent 平台集成 ModelEngine 数据工程与模型工程完整指南
本指南面向需要在 Nexent 平台中打通"数据 → 模型 → AI 应用"全链路的技术开发者,系统讲解如何集成 ModelEngine 的模型工程(ModelLite)与数据工程(DataMate),并附以仓库源码级实现解析。阅读完成后,你将掌握模型同步、知识库接入、
datamate_search工具配置以及知识库检索 Agent 的完整搭建方法。
1. ModelEngine 集成总览
ModelEngine 是一套端到端的 AI 工具链,覆盖数据处理、知识生成、模型微调与部署,以及 RAG(检索增强生成)应用开发,目标是缩短"从数据到模型、从数据到 AI 应用部署"的周期。它提供低代码编排、灵活的调度执行、高性能数据总线等技术,并内置数据处理算子与 RAG 框架。
在 Nexent 平台中,ModelEngine 的集成分为两条主线:
- 模型工程(ModelLite):模型微调与推理托管工具链。接入后可将 ModelEngine 平台上部署的各类模型同步到 Nexent,用于对话生成(LLM)、知识库向量化(Embedding)、图片理解(VLM)等场景。
- 数据工程(DataMate):面向模型微调与 RAG 检索的企业级数据处理平台。接入后可复用 DataMate 知识库资源,并让 Nexent 中的 Agent 通过
datamate_search工具检索这些文档。
两条主线的完整源码参考:backend/services/providers/modelengine_provider.py(模型同步)与 backend/services/datamate_service.py(知识库同步)。
需要特别注意的是,ModelEngine 相关功能由一个部署级开关控制,未开启前前端不会展示对应配置入口(详见下文第 2.2 节)。
2. 集成模型工程(ModelLite)
2.1 ModelLite 能力概览
ModelLite 是模型微调与推理托管的工具链。在 Nexent 中完成 ModelEngine 模型服务接入后,可以获得以下能力:
- 同步 ModelEngine 平台上已部署的全部模型;
- 使用大语言模型(LLM)进行对话生成;
- 使用 Embedding 模型处理知识库向量化;
- 使用视觉语言模型(VLM)处理图片理解任务。
2.2 部署前提:开启 MODEL_ENGINE_ENABLED
ModelEngine 集成的所有功能都由环境变量 MODEL_ENGINE_ENABLED 控制。该变量的定义位于 backend/consts/const.py:
MODEL_ENGINE_ENABLED = os.getenv("MODEL_ENGINE_ENABLED")
默认值为 false,部署时需要显式打开:
-
Docker Compose 部署:修改
.env文件中MODEL_ENGINE_ENABLED的值,参考 deploy/docker/compose/docker-compose.yml:- MODEL_ENGINE_ENABLED=${MODEL_ENGINE_ENABLED:-false} -
Kubernetes / Helm 部署:通过 values 配置
config.modelEngine.enabled,由 deploy/k8s/helm/nexent/charts/nexent-common/templates/configmap.yaml 注入到 ConfigMap,并在 web 服务的 deployment.yaml 中挂载为环境变量。
开启后,后端配置服务会在加载应用配置时向前端下发开关状态(见 backend/services/config_sync_service.py):
"modelEngineEnabled": str(MODEL_ENGINE_ENABLED).lower() == "true"
前端知识库配置页也会依据该开关决定同步行为:开启时同步本地知识库与 DataMate 知识库,关闭时仅同步本地知识库(参考 frontend/app/[locale]/knowledges/KnowledgeBaseConfiguration.tsx)。
2.3 获取 ModelEngine 凭据
- 访问你的 ModelEngine 平台;
- 创建一个 API Key(用于鉴权);
- 记录 ModelEngine 主机地址,格式为
https://<host>:<port>。
⚠️ 注意:请确保已在 ModelEngine 上部署所需的模型,否则同步后列表为空。
2.4 在 Nexent 中配置 ModelEngine 模型
- 登录 Nexent 平台;
- 进入 模型管理(Model Management) 页面;
- 在 模型设置(Model Settings) 中点击 同步 ModelEngine 配置(Sync ModelEngine Configuration) 按钮;
- 在弹出的表单中填写以下信息:
- Host Address(主机地址):ModelEngine 服务地址,如
https://<host>:<port>; - Model Type(模型类型):选择要接入的模型类型;
- API Key:ModelEngine 平台的 API Key;
- Host Address(主机地址):ModelEngine 服务地址,如
- 点击 Get Models(获取模型) 按钮,系统会自动拉取 ModelEngine 上所有可用模型,并按需启用;
- 同步成功的模型会出现在模型列表中,来源标记为 ModelEngine。
2.5 源码级实现解析:模型如何被同步
模型同步的后端实现位于 backend/services/providers/modelengine_provider.py,其核心逻辑如下。
北向接口前缀:MODEL_ENGINE_NORTH_PREFIX = "open/router/v1",同步请求实际调用的是:
GET {model_engine_host}/open/router/v1/models
Authorization: Bearer {api_key}
请求使用 aiohttp 且显式关闭 SSL 校验(aiohttp.TCPConnector(ssl=False)),这是因为 ModelEngine 北向端点通常使用自签名证书。
模型类型映射:ModelEngine 返回的模型 type 字段会被映射为 Nexent 内部模型类型:
| ModelEngine 类型 | Nexent 内部类型 | 用途 |
|---|---|---|
chat |
llm |
对话生成 |
embed |
embedding |
知识库向量化 |
multimodal |
vlm |
图片理解 |
asr |
vlm4 |
语音识别 |
tts |
tts |
语音合成 |
rerank |
rerank |
检索结果重排 |
URL 识别与安全处理:backend/consts/provider.py 定义了 MODEL_ENGINE_URL_MARKER = "open/router" 作为识别 ModelEngine 北向端点的路径标记。在 backend/services/model_management_service.py 中,只要 base_url 包含该标记:
- 自动设置
ssl_verify=False(适配自签名证书); - 自动将
model_factory置为"modelengine",从而在运行时走对应的消息格式适配逻辑(见 backend/services/conversation_management_service.py,ModelEngine 需要将消息扁平化为简单的 role/content 结构)。
预置目录:backend/configs/model_catalog.json 中预置了 modelengine 提供方的默认配置,包含 qwen3-8b(context_window_tokens 131072、max_output_tokens 8192)等模型参数,同步时可作为兜底默认值。
提示:用户填写的 Host Address 即使带上了
/open/router/v1之类的路径,也会先经get_model_engine_raw_url()剥离开来还原出主机基址,再统一拼接北向前缀(见 modelengine_provider.py)。
3. 集成数据工程(DataMate)
3.1 DataMate 是什么
DataMate 是面向模型微调与 RAG 检索的企业级数据处理平台,核心功能包括数据采集、数据管理、算子市场、数据清洗、数据合成、数据标注、数据评估与知识生成。接入 DataMate 后,你可以:
- 复用已有的 DataMate 知识库资源;
- 让 Nexent 中的 Agent 检索 DataMate 文档。
从源码结构看,DataMate 在 Nexent 中被抽象为一种向量数据库类型(VectorDatabaseType.DATAMATE),与 Elasticsearch 平级。当知识库使用 DataMate 作为存储后端时,系统会从租户配置中读取 DATAMATE_URL 并实例化 DataMateCore 客户端(见 backend/management/services/knowledge_base/common.py)。
3.2 安装并启动 DataMate 服务
首先需要部署 DataMate 服务,具体安装步骤请查阅 DataMate 官方文档。启动后记录 DataMate 服务地址,例如 https://<host>:<port>。
3.3 在 Nexent 中配置 DataMate 并同步知识库
- 登录 Nexent 平台;
- 进入 知识库(Knowledge Base) 页面;
- 点击 DataMate 配置(DataMate Configuration) 按钮;
- 填写 DataMate 服务地址:
- Datamate URL:DataMate 服务地址,如
https://<host>:<port>;
- Datamate URL:DataMate 服务地址,如
- 点击 同步(Sync) 按钮,系统会自动拉取 DataMate 上的全部知识库;
- 同步成功后,知识库会出现在知识库列表中,来源标记为 DataMate。
配置的 Datamate URL 会被持久化到租户级配置键 DATAMATE_URL 中(见 backend/consts/const.py),并由 backend/services/config_sync_service.py 在下一次加载配置时回传给前端。
对应的后端接口(backend/apps/datamate_app.py):
| 接口 | 方法 | 作用 |
|---|---|---|
/datamate/sync_datamate_knowledges |
POST | 同步全部 DataMate 知识库并在本地数据库创建记录 |
/datamate/{knowledge_base_id}/files |
GET | 获取指定 DataMate 知识库的文件列表 |
/datamate/test_connection |
POST | 测试与 DataMate 服务的连接 |
同步流程的完整实现位于 backend/services/datamate_service.py:
- 优先使用请求传入的
datamate_url,否则回退到租户配置中的DATAMATE_URL;未配置时跳过同步并返回空结果; - 调用
DataMateCore.get_user_indices()获取知识库 ID 列表; - 调用
get_indices_detail()获取各知识库的详细信息(含 embedding 模型名); - 通过
_create_datamate_knowledge_records()在本地数据库逐条 upsert 知识记录,其中knowledge_sources标记为"datamate"(见 datamate_service.py),这就是前端列表中"来源为 DataMate"标识的数据基础; - 对比本地已有记录与 API 返回的索引,对已在 DataMate 删除的知识库执行软删除,保证列表与远端一致。
此外,check_datamate_connection() 会先检查 MODEL_ENGINE_ENABLED 是否为 true——如果开关未开启,连接测试会直接返回失败并提示 "ModelEngine is disabled",这一点与第 2.2 节的前提要求一致。
3.4 创建或编辑知识库检索 Agent
- 进入 Agent 开发(Agent Development) 页面;
- 新建一个 Agent,或编辑现有的 Agent。
3.5 为 Agent 添加 datamate_search 工具
在 Agent 配置页面中:
- 找到 工具配置(Tool Configuration) 区域;
- 点击 本地工具(Local Tools)> 搜索(Search);
- 从工具列表中选择
datamate_search工具,用于检索 DataMate 知识库; - 配置
datamate_search工具参数:- a) 填写 DataMate 服务地址(通常已根据之前的配置自动填充);
- b) 点击 选择知识库(Select Knowledge Base) 按钮;
- c) 从知识库列表中选择要检索的 DataMate 知识库(支持多选);
- d) 点击 确认(Confirm) 保存配置。
工具的完整参数说明(来自 sdk/nexent/core/tools/datamate_search_tool.py):
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
server_url |
string | 必填 | DataMate 服务地址,如 https://192.168.1.100:8080;必须包含协议头 |
verify_ssl |
boolean | false | 是否校验 HTTPS 的 SSL 证书(适配自签名证书场景) |
index_names |
list[string] | 空 | 要检索的知识库索引列表(即前端选择的知识库) |
top_k |
int | 3 | 返回的搜索结果最大数量,取值 1–100 |
threshold |
float | 0.2 | 搜索结果相似度阈值,取值 0.0–1.0,作为混合检索的精确度权重 |
rerank |
boolean | false | 是否对搜索结果启用重排 |
rerank_model_name |
string | 空 | 使用的重排模型名称 |
kb_page |
int | 1 | 从 DataMate 列出知识库时的页码 |
kb_page_size |
int | 20 | 列出知识库时的每页大小,上限 100 |
说明:工具初始化时会解析
server_url的协议、主机与端口(缺省端口按 https 取 443、http 取 80),并校验端口范围 1–65535;未指定verify_ssl时,HTTPS 默认不校验证书、HTTP 默认校验(见 datamate_search_tool.py)。
3.6 源码级实现解析:检索与重排
datamate_search 的检索链路(sdk/nexent/core/tools/datamate_search_tool.py):
- 若未选择任何知识库(
index_names为空),直接返回"未选择知识库,未找到相关信息"; - 对每个选中的知识库调用
DataMateCore.hybrid_search()执行混合检索(weight_accurate取阈值参数); - 若启用重排(
rerank=True且配置了重排模型),会先以top_k × RERANK_OVERSEARCH_MULTIPLIER的倍数多召回候选,再交由重排模型精选top_k条(重排失败时自动回退到原始结果); - 将每条命中结果解析为带
source_type="datamate"、标题、文本、下载 URL、分数、引用编号的结构化消息,同时通过observer在对话流中展示搜索卡片与详情。
其中对 DataMate 服务侧的 API 调用由 sdk/nexent/datamate/datamate_client.py 统一封装,主要端点如下:
| 方法 | DataMate API | 作用 |
|---|---|---|
list_knowledge_bases() |
POST /api/knowledge-base/list |
分页拉取全部知识库(自动翻页聚合) |
get_knowledge_base_files() |
GET /api/knowledge-base/{id}/files |
获取知识库文件列表 |
get_knowledge_base_info() |
GET /api/knowledge-base/{id} |
获取知识库详情 |
retrieve_knowledge_base() |
POST /api/knowledge-base/retrieve |
按 query、topK、threshold、knowledgeBaseIds 检索 |
build_file_download_url() |
— | 拼接文件下载地址 /api/data-management/datasets/{dataset_id}/files/{file_id}/download |
后端在实例化工具时,会为 dify_search 与 datamate_search 统一注入租户已配置的重排模型(见 backend/services/tool_configuration_service.py),并在工具测试面板中实际调用 forward() 验证配置可用性。
4. 综合实战:搭建一个知识库检索 Agent
下面完整串联模型工程与数据工程两条主线,搭建一个"基于 DataMate 知识库回答问题"的检索 Agent。
4.1 配置 ModelEngine 模型
- 进入 模型管理(Model Management) 页面;
- 点击 ModelEngine 配置,填写 API Key 与主机地址;
- 同步模型后,选择一个 LLM 作为 Agent 的运行模型。
验证点:同步成功后,模型列表会出现来源为 ModelEngine 的模型卡片(前端来源标识见 frontend/app/[locale]/models/components/model/ModelListCard.tsx)。若列表为空,请确认 ModelEngine 上已部署对应模型,且 MODEL_ENGINE_ENABLED 已开启。
4.2 接入 DataMate 知识库
- 进入 知识库(Knowledge Base) 页面;
- 点击 DataMate 配置,填写 DataMate 服务地址;
- 点击同步 DataMate 知识库,获取可用的知识库列表。
验证点:同步成功后,知识库列表中出现来源为 DataMate 的知识库条目;其底层是本地数据库中 knowledge_sources="datamate" 的记录(见 datamate_service.py)。
4.3 创建 Agent 并配置工具
-
进入 Agent 管理(Agent Management),新建一个 Agent;
-
在工具配置中添加
datamate_search工具; -
选择已同步的 DataMate 知识库(可多选);
-
编写系统提示词,例如:
"You are a professional product assistant. You can answer user questions based on documents from the Datamate knowledge base."
4.4 测试验证
在聊天页面与 Agent 交互,提出与产品相关的问题。Agent 会自动通过 datamate_search 工具在 DataMate 知识库中检索相关内容并给出回答,同时展示带引用编号的检索结果卡片与可跳转的文件下载链接。
测试覆盖参考:仓库中已有针对该链路的自动化测试,例如 test/backend/services/test_datamate_service.py(覆盖同步、连接测试、开关未开启时的行为)与 test/sdk/core/tools/test_datamate_search_tool.py,可用于回归验证集成行为。
5. 相关资源
继续深入阅读与本文主题相关的仓库文档与源码:
- 本文中文版本:doc/docs/zh/user-guide/modelengine.md
- 本地搜索工具使用说明:doc/docs/en/user-guide/local-tools/search-tools.md
- ModelEngine 提供方实现:backend/services/providers/modelengine_provider.py
- ModelEngine URL 识别与提供方常量:backend/consts/provider.py
- DataMate 同步服务层:backend/services/datamate_service.py
- DataMate API 网关层:backend/apps/datamate_app.py
datamate_search工具(SDK):sdk/nexent/core/tools/datamate_search_tool.py- DataMate 客户端封装(SDK):sdk/nexent/datamate/datamate_client.py
- 模型目录预置配置:backend/configs/model_catalog.json
6. 技术排障要点
- 模型同步列表为空:先确认 ModelEngine 上已部署所需模型,再检查
MODEL_ENGINE_ENABLED是否为true(该开关同时影响 DataMate 连接测试,关闭时后端会直接返回 "ModelEngine is disabled"); - HTTPS 证书报错:ModelEngine 北向端点使用自签名证书时,系统默认关闭 SSL 校验(
ssl_verify=False),请勿手动改为校验模式,否则连接会失败; - DataMate 连接失败:通过
/datamate/test_connection接口或前端按钮先做连通性测试,同时确认租户级DATAMATE_URL已正确保存; - 检索无结果:尝试降低
threshold相似度阈值、增大top_k,或确认index_names中已正确选择同步过来的知识库。