Nexent 平台集成 ModelEngine 数据工程与模型工程完整指南

原创2026-10-12 23:17:561,857 阅读
文章标签:AI AgentAI 应用后端前端大模型RAG

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,部署时需要显式打开:

开启后,后端配置服务会在加载应用配置时向前端下发开关状态(见 backend/services/config_sync_service.py):

"modelEngineEnabled": str(MODEL_ENGINE_ENABLED).lower() == "true"

前端知识库配置页也会依据该开关决定同步行为:开启时同步本地知识库与 DataMate 知识库,关闭时仅同步本地知识库(参考 frontend/app/[locale]/knowledges/KnowledgeBaseConfiguration.tsx)。

2.3 获取 ModelEngine 凭据

  1. 访问你的 ModelEngine 平台;
  2. 创建一个 API Key(用于鉴权);
  3. 记录 ModelEngine 主机地址,格式为 https://<host>:<port>。

⚠️ 注意:请确保已在 ModelEngine 上部署所需的模型,否则同步后列表为空。

2.4 在 Nexent 中配置 ModelEngine 模型

  1. 登录 Nexent 平台;
  2. 进入 模型管理(Model Management) 页面;
  3. 在 模型设置(Model Settings) 中点击 同步 ModelEngine 配置(Sync ModelEngine Configuration) 按钮;
  4. 在弹出的表单中填写以下信息:
    • Host Address(主机地址):ModelEngine 服务地址,如 https://<host>:<port>;
    • Model Type(模型类型):选择要接入的模型类型;
    • API Key:ModelEngine 平台的 API Key;
  5. 点击 Get Models(获取模型) 按钮,系统会自动拉取 ModelEngine 上所有可用模型,并按需启用;
  6. 同步成功的模型会出现在模型列表中,来源标记为 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 并同步知识库

  1. 登录 Nexent 平台;
  2. 进入 知识库(Knowledge Base) 页面;
  3. 点击 DataMate 配置(DataMate Configuration) 按钮;
  4. 填写 DataMate 服务地址:
    • Datamate URL:DataMate 服务地址,如 https://<host>:<port>;
  5. 点击 同步(Sync) 按钮,系统会自动拉取 DataMate 上的全部知识库;
  6. 同步成功后,知识库会出现在知识库列表中,来源标记为 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:

  1. 优先使用请求传入的 datamate_url,否则回退到租户配置中的 DATAMATE_URL;未配置时跳过同步并返回空结果;
  2. 调用 DataMateCore.get_user_indices() 获取知识库 ID 列表;
  3. 调用 get_indices_detail() 获取各知识库的详细信息(含 embedding 模型名);
  4. 通过 _create_datamate_knowledge_records() 在本地数据库逐条 upsert 知识记录,其中 knowledge_sources 标记为 "datamate"(见 datamate_service.py),这就是前端列表中"来源为 DataMate"标识的数据基础;
  5. 对比本地已有记录与 API 返回的索引,对已在 DataMate 删除的知识库执行软删除,保证列表与远端一致。

此外,check_datamate_connection() 会先检查 MODEL_ENGINE_ENABLED 是否为 true——如果开关未开启,连接测试会直接返回失败并提示 "ModelEngine is disabled",这一点与第 2.2 节的前提要求一致。

3.4 创建或编辑知识库检索 Agent

  1. 进入 Agent 开发(Agent Development) 页面;
  2. 新建一个 Agent,或编辑现有的 Agent。

3.5 为 Agent 添加 datamate_search 工具

在 Agent 配置页面中:

  1. 找到 工具配置(Tool Configuration) 区域;
  2. 点击 本地工具(Local Tools)> 搜索(Search);
  3. 从工具列表中选择 datamate_search 工具,用于检索 DataMate 知识库;
  4. 配置 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):

  1. 若未选择任何知识库(index_names 为空),直接返回"未选择知识库,未找到相关信息";
  2. 对每个选中的知识库调用 DataMateCore.hybrid_search() 执行混合检索(weight_accurate 取阈值参数);
  3. 若启用重排(rerank=True 且配置了重排模型),会先以 top_k × RERANK_OVERSEARCH_MULTIPLIER 的倍数多召回候选,再交由重排模型精选 top_k 条(重排失败时自动回退到原始结果);
  4. 将每条命中结果解析为带 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 模型

  1. 进入 模型管理(Model Management) 页面;
  2. 点击 ModelEngine 配置,填写 API Key 与主机地址;
  3. 同步模型后,选择一个 LLM 作为 Agent 的运行模型。

验证点:同步成功后,模型列表会出现来源为 ModelEngine 的模型卡片(前端来源标识见 frontend/app/[locale]/models/components/model/ModelListCard.tsx)。若列表为空,请确认 ModelEngine 上已部署对应模型,且 MODEL_ENGINE_ENABLED 已开启。

4.2 接入 DataMate 知识库

  1. 进入 知识库(Knowledge Base) 页面;
  2. 点击 DataMate 配置,填写 DataMate 服务地址;
  3. 点击同步 DataMate 知识库,获取可用的知识库列表。

验证点:同步成功后,知识库列表中出现来源为 DataMate 的知识库条目;其底层是本地数据库中 knowledge_sources="datamate" 的记录(见 datamate_service.py)。

4.3 创建 Agent 并配置工具

  1. 进入 Agent 管理(Agent Management),新建一个 Agent;

  2. 在工具配置中添加 datamate_search 工具;

  3. 选择已同步的 DataMate 知识库(可多选);

  4. 编写系统提示词,例如:

    "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. 相关资源

继续深入阅读与本文主题相关的仓库文档与源码:

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 中已正确选择同步过来的知识库。
登录后查看全文
nexent