Nexent 对接 ModelEngine:ModelLite 模型工程与 DataMate 数据工程全流程配置指南
Nexent 对接 ModelEngine:ModelLite 模型工程与 DataMate 数据工程全流程配置指南
本文是 Nexent 零代码 AI Agent 平台对接 ModelEngine 生态的实操指南,覆盖模型工程(ModelLite)与数据工程(DataMate)两大对接链路:从部署开关、API 凭证获取、模型同步,到知识库同步与
datamate_search检索工具配置,并深入到仓库源码层面解释底层实现(模型类型映射、SSL 处理、同步与软删除逻辑)。读者按文操作后,可以独立完成"ModelEngine 模型 + DataMate 知识库"驱动的知识检索型智能体的搭建与测试。
1. ModelEngine 是什么
ModelEngine 提供从数据处理、知识生成,到模型微调和部署,以及 RAG(Retrieval Augmented Generation)应用开发的 AI 训推全流程工具链,用于缩短从数据到模型、数据到 AI 应用的落地周期。ModelEngine 提供低代码编排、灵活的执行调度、高性能数据总线等技术,结合内置的数据处理算子、RAG 框架以及广泛的生态能力,为数据开发工程师、模型开发工程师、应用开发工程师提供高效易用、开放灵活、开箱即用、轻量的全流程 AI 开发体验。
在 Nexent 中,ModelEngine 生态的对接被拆分为两条独立的链路:
- 模型工程(ModelLite):面向模型微调与模型推理的工具链,托管并提供多种 AI 模型的访问服务;
- 数据工程(DataMate):面向模型微调与 RAG 检索的企业级数据处理平台,提供知识库资源。
两条链路在 Nexent 的模型管理页与知识库页分别配置,最终统一服务于智能体的"模型能力 + 检索能力"。
2. 对接模型工程(ModelLite)
2.1 对接后可以获得的能力
在 Nexent 中对接 ModelLite 模型服务后,您可以:
- 同步在 ModelEngine 平台上部署的所有模型;
- 使用**大语言模型(LLM)**进行对话生成;
- 使用**向量化模型(Embedding)**进行知识库处理;
- 使用**视觉语言模型(VLM)**处理图片。
也就是说,ModelEngine 上部署的模型会被纳入 Nexent 的模型管理体系中,成为智能体运行时可选择的模型来源。
2.2 前置条件:开启 MODEL_ENGINE_ENABLED 部署开关
对接 ModelEngine 属于可选能力,默认关闭。部署 Nexent 时,需要通过环境变量显式开启,否则前端不会显示"同步 ModelEngine 配置"入口,后端也会跳过相关逻辑(如 DataMate 连接测试会直接返回 ModelEngine is disabled)。
该开关在源码中的定义位置为 backend/consts/const.py:
# Model Engine Configuration
MODEL_ENGINE_ENABLED = os.getenv("MODEL_ENGINE_ENABLED")
不同部署方式下的开启方法:
- Docker Compose 部署:在
.env文件中将MODEL_ENGINE_ENABLED变量值改为True。Compose 文件中的默认值为false,见 deploy/docker/compose/docker-compose.yml:- MODEL_ENGINE_ENABLED=${MODEL_ENGINE_ENABLED:-false} - Kubernetes / Helm 部署:通过 values 配置开启,见 deploy/k8s/helm/nexent/charts/nexent-common/values.yaml:
该值最终注入到 ConfigMap(deploy/k8s/helm/nexent/charts/nexent-common/templates/configmap.yaml)与 Web 端 Deployment 环境变量(deploy/k8s/helm/nexent/charts/nexent-web/templates/deployment.yaml)。modelEngine: enabled: "false"
后端在向客户端同步平台配置时,也会将 modelEngineEnabled 一并下发(见 backend/services/config_sync_service.py):
"modelEngineEnabled": str(MODEL_ENGINE_ENABLED).lower() == "true"
⚠️ 注意:请确保您已在 ModelEngine 平台上部署了需要的模型,否则同步后将无法看到模型列表。
2.3 配置步骤
步骤 1:获取 ModelEngine 访问凭证
- 访问您的 ModelEngine 平台;
- 创建 API Key(用于身份验证);
- 记录 ModelEngine 的主机地址(格式:
https://<host>:<port>)。
步骤 2:在 Nexent 中配置 ModelEngine 模型
- 登录 Nexent 平台;
- 进入 模型管理 页面;
- 点击 模型设置 中的 同步 ModelEngine 配置 按钮;
- 在弹窗中填写以下信息:
- 主机地址:ModelEngine 服务的 URL(如
https://<host>:<port>); - 模型类型:选择对接的模型类型(LLM / Embedding / VLM 等);
- API Key:ModelEngine API Key;
- 主机地址:ModelEngine 服务的 URL(如
- 配置完成后,点击 获取模型 按钮,系统将自动获取 ModelEngine 上部署的所有可用模型,根据需要启用对应的模型;
- 同步成功的模型将显示在模型列表中,并标记为 "ModelEngine" 来源。
前端通过 MODEL_SOURCES.MODELENGINE 对模型进行来源标记与展示,相关定义可参考 frontend/const/modelConfig.ts 与 frontend/app/[locale]/models/components/model/ModelItemCard.tsx。
2.4 源码原理:ModelEngine 模型拉取与类型映射
Nexent 将 ModelEngine 作为一个独立的模型提供方(Provider)进行调度。提供方枚举定义在 backend/consts/provider.py:
class ProviderEnum(str, Enum):
"""Supported model providers"""
SILICON = "silicon"
OPENAI = "openai"
MODELENGINE = "modelengine"
DASHSCOPE = "dashscope"
TOKENPONY = "tokenpony"
模型拉取由专门的 ModelEngineProvider 实现,见 backend/services/providers/modelengine_provider.py。与 OpenAI 兼容提供商走 /models 标准路径不同,ModelEngine 的模型列表端点位于 {host}/open/router/v1/models(常量 MODEL_ENGINE_NORTH_PREFIX = "open/router/v1"),请求携带 Authorization: Bearer <api_key> 头,并且因为其端点常服务于自签名证书,HTTP 连接显式关闭了 SSL 验证:
MODEL_ENGINE_NORTH_PREFIX = "open/router/v1"
headers = {"Authorization": f"Bearer {api_key}"}
async with aiohttp.ClientSession(
timeout=aiohttp.ClientTimeout(total=30),
connector=aiohttp.TCPConnector(ssl=False)
) as session:
async with session.get(
f"{model_engine_url.rstrip('/')}/{MODEL_ENGINE_NORTH_PREFIX}/models",
headers=headers
) as response:
...
ModelEngine 返回的模型自带一套类型体系,需要映射到 Nexent 内部的模型类型,映射表如下(源码见 backend/services/providers/modelengine_provider.py):
| ModelEngine 原始类型 | Nexent 内部类型 | 说明 |
|---|---|---|
chat |
llm |
大语言模型,用于对话生成 |
embed |
embedding |
向量化模型,用于知识库处理 |
multimodal |
vlm |
视觉语言模型,处理图片 |
asr |
vlm4 |
语音识别 |
tts |
tts |
语音合成 |
rerank |
rerank |
重排序模型 |
如果配置时指定了"模型类型"过滤条件,仅与过滤类型匹配的模型会被保留;每个模型还会携带自己的 base_url(如 https://120.253.225.102:50001),供后续构造完整的调用地址使用。模型同步的分发入口在 backend/services/model_provider_service.py,当 provider 为 modelengine 时,走 ModelEngineProvider,其余提供商走标准的 OpenAI 兼容 Provider。
3. 对接数据工程(DataMate)
3.1 什么是 DataMate
DataMate 是面向模型微调与 RAG 检索的企业级数据处理平台,支持数据归集、数据管理、算子市场、数据清洗、数据合成、数据标注、数据评估、知识生成等核心功能。通过对接 DataMate,您可以:
- 复用已有的 DataMate 知识库资源;
- 在 Nexent 智能体中检索 DataMate 中的文档。
3.2 配置步骤
步骤 1:安装和启动 DataMate 服务
首先,您需要部署 DataMate 服务。启动后,记录 DataMate 的服务地址(如 https://<host>:<port>)。DataMate 的详细安装方式以对应官方文档为准。
步骤 2:在 Nexent 中配置 DataMate
- 登录 Nexent 平台;
- 进入 知识库 页面;
- 点击 DataMate 配置 按钮;
- 填写 DataMate 服务器地址:
- Datamate URL:DataMate 服务的地址(如
https://<host>:<port>);
- Datamate URL:DataMate 服务的地址(如
- 配置完成后,点击 同步 按钮,系统将自动获取 DataMate 中的所有知识库;
- 同步成功后,知识库将显示在知识库列表中,标记来源为 "DataMate"。
步骤 3:创建或编辑知识库检索智能体
- 进入 智能体开发 页面;
- 创建新智能体或编辑现有智能体。
步骤 4:添加 datamate_search 工具
在智能体配置页面:
- 找到 工具配置 部分;
- 点击 本地工具 > search 按钮;
- 从工具列表中选择
datamate_search工具:用于检索 DataMate 知识库; - 配置
datamate_search工具参数:- a) 填写 DataMate 服务器地址(通常会自动填充您之前配置的地址);
- b) 点击 选择知识库 按钮;
- c) 从知识库列表中选择要检索的 DataMate 知识库(可多选);
- d) 点击 确定 保存配置。
前端工具配置弹窗对 datamate_search 有专门的初始化逻辑(自动回填 DataMate URL 等),实现可参考 frontend/app/[locale]/agents/components/capability/tool/ToolConfigModal.tsx。
datamate_search 工具参数详解
Nexent 本地搜索工具的完整参数说明见 doc/docs/zh/user-guide/local-tools/search-tools.md,其中 datamate_search 的核心参数如下:
| 类别 | 参数 | 说明 |
|---|---|---|
| 配置参数 | server_url |
DataMate 服务地址(如 http://192.168.1.100:8080 或 https://datamate.example.com:8443) |
| 配置参数 | verify_ssl |
是否验证 SSL 证书(HTTPS 默认 False,HTTP 默认 True) |
| 检索参数 | query |
检索问题,必填 |
| 检索参数 | top_k |
返回数量,默认 3 |
| 检索参数 | threshold |
相似度阈值,默认 0.2 |
| 检索参数 | index_names |
指定要搜索的知识库名称列表,可选 |
| 检索参数 | kb_page / kb_page_size |
分页获取 DataMate 知识库列表 |
| 检索参数 | enable_rerank |
是否启用重排序,默认 False;开启后会对检索结果二次排序,提升相关性 |
| 检索参数 | rerank_model |
重排序使用的模型,默认为系统配置的 rerank 模型,enable_rerank 为 True 时生效 |
检索结果包含文件名、下载链接、得分等结构化信息。工具实例化时后端会按需注入 rerank 模型配置,相关逻辑见 backend/services/tool_configuration_service.py。
3.3 源码原理:DataMate 同步、检索与软删除
同步服务层
DataMate 对接的服务层位于 backend/services/datamate_service.py,路由层位于 backend/apps/datamate_app.py,对外提供三个核心接口:
| HTTP 接口 | 作用 |
|---|---|
POST /datamate/sync_datamate_knowledges |
同步 DataMate 全部知识库并在本地数据库创建知识记录 |
GET /datamate/{knowledge_base_id}/files |
获取指定 DataMate 知识库的文件列表 |
POST /datamate/test_connection |
测试 DataMate 服务器连通性 |
同步流程(sync_datamate_knowledge_bases_and_create_records)的核心步骤:
- 以请求中的
datamate_url优先、租户配置兜底确定有效地址(未配置时安全返回空结果); - 调用
get_user_indices获取知识库 ID 列表; - 调用
get_indices_detail获取每个知识库的详细信息(名称、文件数、Chunk 数、存储大小、Embedding 模型名等); - 在本地数据库创建/更新知识记录:
index_name使用 DataMate 知识库 ID,knowledge_sources标记为datamate,embedding_model_name取 DataMate 知识库自身配置的 Embedding 模型(见 backend/services/datamate_service.py); - 软删除清理:对比本地已存在记录与 DataMate 返回的知识库 ID 集合,将"本地有但 DataMate 已不存在"的记录软删除,保证列表与远端一致。
连接测试的开关依赖
check_datamate_connection 会首先检查 MODEL_ENGINE_ENABLED 是否为 true,否则直接返回 ModelEngine is disabled(见 backend/services/datamate_service.py)。这与 2.2 节的部署开关一致:DataMate 对接同样依赖该开关开启。
自签名证书处理
服务层构造 DataMate 客户端时,对 HTTPS 地址默认关闭 SSL 验证(verify_ssl = not datamate_server_url.startswith("https://"),见 backend/services/datamate_service.py),以适配企业内网常见的自签名证书场景。
SDK 层:DataMateCore 与 DataMateClient
Nexent SDK 以 VectorDatabaseCore 接口抽象向量数据库能力,DataMate 的适配实现位于 sdk/nexent/vector_database/datamate_core.py。由于 DataMate HTTP API 的能力边界,索引创建/删除、文档写入、Chunk 级操作等方法显式抛出 NotImplementedError 表明不支持;实际支持的检索为 hybrid_search(见 sdk/nexent/vector_database/datamate_core.py),它忽略本地 Embedding 模型、直接调用 DataMate 的检索接口。
底层 HTTP 客户端为 sdk/nexent/datamate/datamate_client.py,封装了:
list_knowledge_bases():列出知识库;get_knowledge_base_info(kb_id):知识库详情;get_knowledge_base_files(kb_id):知识库文件列表;retrieve_knowledge_base(query, knowledge_base_ids, top_k, threshold):检索内容。
其中检索请求为 POST /api/knowledge-base/retrieve,载荷包含 query、topK、threshold、knowledgeBaseIds 四个字段(见 sdk/nexent/datamate/datamate_client.py)。客户端通过共享的 HttpClientManager 复用连接,避免 Windows 下 socket 耗尽与端口冲突问题。
4. 综合使用示例:创建一个知识库检索智能体
将两条链路串起来,即可构建一个基于 Datamate 知识库回答问题的检索增强智能体:
-
配置 ModelEngine 模型
- 进入模型管理页面;
- 点击 ModelEngine 配置,填写 API Key 和主机地址;
- 同步模型后,选择一个大语言模型作为智能体的运行模型。
-
对接 DataMate 知识库
- 进入知识库页面;
- 点击 DataMate 配置,填写 DataMate 服务器地址;
- 点击同步 DataMate 知识库,获取可用的知识库列表。
-
创建智能体
- 进入智能体管理,创建新智能体;
- 在工具配置中添加
datamate_search工具; - 选择已同步的 DataMate 知识库;
- 编写系统提示词,例如:"你是一个专业的产品助手,可以根据 Datamate 知识库中的文档回答用户问题。"
-
测试使用
- 在对话页面与智能体交互;
- 询问产品相关问题,智能体将自动从 DataMate 知识库检索相关内容并回答。
整体链路为:用户提问 → 智能体(运行在 ModelLite 同步来的 LLM 上)→ 调用 datamate_search 工具 → 请求 DataMate /api/knowledge-base/retrieve 接口 → 返回相关文档片段 → LLM 组织答案。
5. 常见问题与排障建议
| 现象 | 排查方向 |
|---|---|
| 模型管理页看不到"同步 ModelEngine 配置"入口 | 确认部署时 MODEL_ENGINE_ENABLED 已设为 True(Docker Compose 改 .env,K8s 改 Helm values config.modelEngine.enabled),并检查后端下发的 modelEngineEnabled 配置 |
| 点击获取模型后模型列表为空 | 确认 ModelEngine 平台上已部署对应类型(chat/embed/multimodal 等)的模型;确认 API Key 有效;确认主机地址可达且格式为 https://<host>:<port> |
| DataMate 同步失败或提示 ModelEngine is disabled | 先确认 MODEL_ENGINE_ENABLED 开关状态;再通过 /datamate/test_connection 接口验证连通性,并检查是否已填写 datamate_url |
| 同步后知识库来源未标记为 DataMate | 检查同步是否成功创建知识记录,本地记录的 knowledge_sources 字段应为 datamate |
| 检索报 SSL 相关错误 | 企业内网自签名证书场景下,确认工具参数 verify_ssl 为 False,或服务端地址以 https:// 开头(后端默认对 HTTPS 关闭验证) |