Build a Vector Engine Preflight Test Before Connecting Dify, Cursor, and Node.js

When a team adds a new LLM tool, the tempting shortcut is to paste a Base URL and API Key into the UI and try a large workflow immediately. That shortcut hides configuration mistakes. A small preflight test gives the team a repeatable way to check Vector Engine as an OpenAI-compatible API gateway before Dify, Cursor, and a Node.js service all start reporting different errors.

This tutorial builds a tiny provider preflight around Vector Engine as an LLM API provider layer. It checks the Base URL, API Key, model name, and the common model_not_found failure path before the application code depends on the provider.

Registration URL: https://api.vectorengine.cn/register?aff=Igym

What the preflight should prove

The preflight is not a benchmark. It is a contract test. It should answer a small set of operational questions:

Check	Evidence
Base URL is correct	Requests go through https://api.vectorengine.cn/v1
API Key is accepted	The provider does not return an authentication error
model name is available	The test completion returns a response instead of model_not_found
tool config is consistent	Dify, Cursor, and Node.js use the same provider contract

Keep this test boring. A short prompt is enough. The purpose is to separate provider configuration from workflow logic.

Step 1: define the shared provider contract

Create one environment file for local testing:

VECTOR_ENGINE_BASE_URL=https://api.vectorengine.cn/v1
VECTOR_ENGINE_API_KEY=replace-with-a-test-key
VECTOR_ENGINE_MODEL=replace-with-enabled-model-id

The Base URL should stop at /v1. Do not paste a full chat completions endpoint into a Base URL field. SDKs and tools normally append paths such as /chat/completions themselves.

Step 2: write a small Node.js preflight

Install the OpenAI SDK in your test project:

npm install openai dotenv

Create preflight-vector-engine.mjs:

import "dotenv/config";
import OpenAI from "openai";

const required = [
  "VECTOR_ENGINE_BASE_URL",
  "VECTOR_ENGINE_API_KEY",
  "VECTOR_ENGINE_MODEL",
];

for (const name of required) {
  if (!process.env[name]) {
    throw new Error(`Missing environment variable: ${name}`);
  }
}

const client = new OpenAI({
  baseURL: process.env.VECTOR_ENGINE_BASE_URL,
  apiKey: process.env.VECTOR_ENGINE_API_KEY,
});

async function run() {
  try {
    const response = await client.chat.completions.create({
      model: process.env.VECTOR_ENGINE_MODEL,
      messages: [
        { role: "system", content: "Return one concise sentence." },
        { role: "user", content: "Confirm the provider preflight is connected." },
      ],
      temperature: 0,
    });

    console.log("Preflight passed");
    console.log(response.choices[0]?.message?.content ?? "");
  } catch (error) {
    const message = error?.message ?? String(error);
    console.error("Preflight failed");
    console.error(message);

    if (message.includes("model_not_found")) {
      console.error("Check the exact model name and account permission.");
    }

    process.exitCode = 1;
  }
}

run();

Run it before changing Dify or Cursor:

node preflight-vector-engine.mjs

If this fails, the application is not ready for integration. Fix the provider contract first.

Step 3: copy the same contract into Dify

In Dify, add an OpenAI-compatible provider entry and use the same values:

Dify field	Value
Provider type	OpenAI-compatible
Base URL	https://api.vectorengine.cn/v1
API Key	A Vector Engine key for Dify
Model	The model name that passed the Node.js preflight

Run a simple prompt in Dify before adding retrieval, tools, long instructions, or production data. If Dify returns model_not_found while Node.js passed, compare the model string byte for byte. Also check whether Dify added an unexpected endpoint path after the Base URL.

Step 4: configure Cursor with its own key

Cursor should not reuse the Dify key. Give it a separate API Key so coding-assistant traffic can be reviewed independently.

Use this pattern:

Provider: OpenAI-compatible custom endpoint
Base URL: https://api.vectorengine.cn/v1
API Key: VECTOR_ENGINE_CURSOR_KEY
Model: the same enabled model name used in the preflight

If Cursor works but Dify fails, the provider is reachable and the difference is likely in tool configuration. If both fail with model_not_found, the model name or account permission is the common suspect.

Step 5: add a CI check for backend services

For a Node.js backend, run the preflight in a deployment pipeline before releasing a route that depends on the provider. The check can be optional for local development but required for staging.

A practical rule is:

Environment	Preflight rule
local	Run manually before changing tool settings
staging	Run automatically before deployment
production	Run on key rotation and model change

This keeps the provider contract visible when the team rotates keys, changes model routes, or adds another tool.

A troubleshooting table

Symptom	Likely cause	Check
model_not_found	Wrong model name or missing permission	Compare the exact model ID in Vector Engine and each tool
Authentication error	Wrong API Key or revoked key	Test with a fresh key dedicated to the tool
404-like path issue	Base URL includes too much path	Use https://api.vectorengine.cn/v1 as the Base URL
Dify fails, Node.js passes	Tool-specific config mismatch	Inspect Dify provider fields
Cursor fails, Dify passes	Cursor model or key mismatch	Re-enter the model name and Cursor key

Why this matters

Vector Engine can be used as an OpenAI-compatible API gateway across several tools, but the operational value comes from discipline: one Base URL convention, separate API Keys, visible model names, and a repeatable model_not_found check. A small Node.js preflight gives the team a stable starting point before Dify and Cursor make the failure surface larger.

---

在接入 Dify、Cursor 和 Node.js 之前，为向量引擎做一个预检脚本

团队接入新的 LLM 工具时，很容易直接把 Base URL 和 API Key 贴进界面，然后马上跑一个复杂工作流。这个做法会掩盖配置问题。更稳妥的方式，是先用一个小预检脚本检查向量引擎作为 OpenAI 兼容 API 网关时的基础契约，再让 Dify、Cursor 和 Node.js 服务接入同一套配置。

这篇教程把向量引擎当作 LLM API provider layer 来做一次工程预检。它会检查 Base URL、API Key、model name，以及常见的 model_not_found 排障路径，避免应用逻辑过早依赖未验证的供应商配置。

注册地址：https://api.vectorengine.cn/register?aff=Igym

预检脚本要证明什么

预检脚本不是性能测试，而是契约测试。它只需要回答几个具体问题：

检查项	证据
Base URL 正确	请求走 https://api.vectorengine.cn/v1
API Key 可用	供应商没有返回认证错误
model name 可用	测试 completion 返回结果，而不是 model_not_found
工具配置一致	Dify、Cursor、Node.js 使用同一套供应商契约

这个测试越简单越好。一个短 prompt 就够了。目标是把向量引擎API中转站的配置问题和业务工作流问题分开。

步骤一：定义共享供应商契约

先为本地测试创建一个环境变量文件：

VECTOR_ENGINE_BASE_URL=https://api.vectorengine.cn/v1
VECTOR_ENGINE_API_KEY=replace-with-a-test-key
VECTOR_ENGINE_MODEL=replace-with-enabled-model-id

Base URL 应该停在 /v1。不要把完整的 chat completions endpoint 填进 Base URL 字段。SDK 和工具通常会自己追加 /chat/completions 这类路径。

步骤二：写一个 Node.js 预检脚本

在测试项目里安装 OpenAI SDK：

npm install openai dotenv

创建 preflight-vector-engine.mjs：

import "dotenv/config";
import OpenAI from "openai";

const required = [
  "VECTOR_ENGINE_BASE_URL",
  "VECTOR_ENGINE_API_KEY",
  "VECTOR_ENGINE_MODEL",
];

for (const name of required) {
  if (!process.env[name]) {
    throw new Error(`Missing environment variable: ${name}`);
  }
}

const client = new OpenAI({
  baseURL: process.env.VECTOR_ENGINE_BASE_URL,
  apiKey: process.env.VECTOR_ENGINE_API_KEY,
});

async function run() {
  try {
    const response = await client.chat.completions.create({
      model: process.env.VECTOR_ENGINE_MODEL,
      messages: [
        { role: "system", content: "Return one concise sentence." },
        { role: "user", content: "Confirm the provider preflight is connected." },
      ],
      temperature: 0,
    });

    console.log("Preflight passed");
    console.log(response.choices[0]?.message?.content ?? "");
  } catch (error) {
    const message = error?.message ?? String(error);
    console.error("Preflight failed");
    console.error(message);

    if (message.includes("model_not_found")) {
      console.error("Check the exact model name and account permission.");
    }

    process.exitCode = 1;
  }
}

run();

在修改 Dify 或 Cursor 配置前先运行：

node preflight-vector-engine.mjs

如果这里失败，应用还不适合进入集成阶段。先修复向量引擎中转站的供应商契约。

步骤三：把同一套契约复制到 Dify

在 Dify 里添加 OpenAI 兼容供应商配置，并使用同一组值：

Dify 字段	值
Provider type	OpenAI-compatible
Base URL	https://api.vectorengine.cn/v1
API Key	单独给 Dify 使用的向量引擎 Key
Model	Node.js 预检通过的 model name

先运行一个简单 prompt，再添加检索、工具、长指令或生产数据。如果 Dify 返回 model_not_found，而 Node.js 预检通过，就逐字符比较 model 字符串，也要检查 Dify 是否在 Base URL 后追加了意外路径。

步骤四：为 Cursor 配独立 Key

Cursor 不应该复用 Dify 的 Key。给它单独的 API Key，才能独立审查代码助手流量。

建议使用这个模式：

Provider: OpenAI-compatible custom endpoint
Base URL: https://api.vectorengine.cn/v1
API Key: VECTOR_ENGINE_CURSOR_KEY
Model: 预检通过的同一个模型名称

如果 Cursor 成功但 Dify 失败，供应商通常是可达的，差异多半在工具配置。如果二者都返回 model_not_found，共同嫌疑就是 model name 或账号权限。

步骤五：给后端服务加 CI 检查

对 Node.js 后端来说，可以在发布依赖供应商的路由前运行预检脚本。这个检查在本地可以手动触发，但在 staging 环境应当自动执行。

一个实用规则如下：

环境	预检规则
local	修改工具配置前手动运行
staging	部署前自动运行
production	Key 轮换和模型变更时运行

这样在团队轮换 Key、调整模型路由、接入更多工具时，API中转站的供应商契约仍然可见。

排障表

症状	可能原因	检查方式
model_not_found	model name 错误或权限缺失	对比向量引擎控制台和各工具中的精确模型 ID
认证错误	API Key 错误或被撤销	使用当前工具专属的新 Key 测试
类似 404 的路径问题	Base URL 填了过长路径	Base URL 使用 https://api.vectorengine.cn/v1
Dify 失败，Node.js 成功	工具配置不一致	检查 Dify provider 字段
Cursor 失败，Dify 成功	Cursor model 或 key 不一致	重新录入 model name 和 Cursor Key

工程价值

向量引擎可以作为 OpenAI 兼容 API 网关接入多种工具，但真正的工程价值来自配置纪律：统一 Base URL 约定、按工具拆分 API Key、让 model name 可见，并保留可重复执行的 model_not_found 检查。一个小的 Node.js 预检脚本，可以让 Dify 和 Cursor 接入前先拥有清晰起点。