Nexent 对接 ModelEngine:ModelLite 模型工程与 DataMate 数据工程全流程配置指南

原创2026-10-12 09:58:501,634 阅读
文章标签:AI AgentAI 应用后端前端大模型RAG

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")

不同部署方式下的开启方法:

后端在向客户端同步平台配置时,也会将 modelEngineEnabled 一并下发(见 backend/services/config_sync_service.py):

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

⚠️ 注意:请确保您已在 ModelEngine 平台上部署了需要的模型,否则同步后将无法看到模型列表。

2.3 配置步骤

步骤 1:获取 ModelEngine 访问凭证

  1. 访问您的 ModelEngine 平台;
  2. 创建 API Key(用于身份验证);
  3. 记录 ModelEngine 的主机地址(格式:https://<host>:<port>)。

步骤 2:在 Nexent 中配置 ModelEngine 模型

  1. 登录 Nexent 平台;
  2. 进入 模型管理 页面;
  3. 点击 模型设置 中的 同步 ModelEngine 配置 按钮;
  4. 在弹窗中填写以下信息:
    • 主机地址:ModelEngine 服务的 URL(如 https://<host>:<port>);
    • 模型类型:选择对接的模型类型(LLM / Embedding / VLM 等);
    • API Key:ModelEngine API Key;
  5. 配置完成后,点击 获取模型 按钮,系统将自动获取 ModelEngine 上部署的所有可用模型,根据需要启用对应的模型;
  6. 同步成功的模型将显示在模型列表中,并标记为 "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

  1. 登录 Nexent 平台;
  2. 进入 知识库 页面;
  3. 点击 DataMate 配置 按钮;
  4. 填写 DataMate 服务器地址:
    • Datamate URL:DataMate 服务的地址(如 https://<host>:<port>);
  5. 配置完成后,点击 同步 按钮,系统将自动获取 DataMate 中的所有知识库;
  6. 同步成功后,知识库将显示在知识库列表中,标记来源为 "DataMate"。

步骤 3:创建或编辑知识库检索智能体

  1. 进入 智能体开发 页面;
  2. 创建新智能体或编辑现有智能体。

步骤 4:添加 datamate_search 工具

在智能体配置页面:

  1. 找到 工具配置 部分;
  2. 点击 本地工具 > search 按钮;
  3. 从工具列表中选择 datamate_search 工具:用于检索 DataMate 知识库;
  4. 配置 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)的核心步骤:

  1. 以请求中的 datamate_url 优先、租户配置兜底确定有效地址(未配置时安全返回空结果);
  2. 调用 get_user_indices 获取知识库 ID 列表;
  3. 调用 get_indices_detail 获取每个知识库的详细信息(名称、文件数、Chunk 数、存储大小、Embedding 模型名等);
  4. 在本地数据库创建/更新知识记录:index_name 使用 DataMate 知识库 ID,knowledge_sources 标记为 datamate,embedding_model_name 取 DataMate 知识库自身配置的 Embedding 模型(见 backend/services/datamate_service.py);
  5. 软删除清理:对比本地已存在记录与 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 知识库回答问题的检索增强智能体:

  1. 配置 ModelEngine 模型

    • 进入模型管理页面;
    • 点击 ModelEngine 配置,填写 API Key 和主机地址;
    • 同步模型后,选择一个大语言模型作为智能体的运行模型。
  2. 对接 DataMate 知识库

    • 进入知识库页面;
    • 点击 DataMate 配置,填写 DataMate 服务器地址;
    • 点击同步 DataMate 知识库,获取可用的知识库列表。
  3. 创建智能体

    • 进入智能体管理,创建新智能体;
    • 在工具配置中添加 datamate_search 工具;
    • 选择已同步的 DataMate 知识库;
    • 编写系统提示词,例如:"你是一个专业的产品助手,可以根据 Datamate 知识库中的文档回答用户问题。"
  4. 测试使用

    • 在对话页面与智能体交互;
    • 询问产品相关问题,智能体将自动从 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 关闭验证)

6. 相关资源

登录后查看全文
nexent