DEV Community

Jia
Jia

Posted on

Add a Vector Engine Startup Self-Test Before a Node.js Service Accepts Traffic

#tutorial #llm #ai #node

A Node.js service can start successfully while its LLM configuration is already broken. The environment variables may exist, but the Base URL may point to the wrong path, the API Key may belong to another tool, or the model name may no longer be enabled. The failure only appears later, when a user request reaches Dify, Cursor, or the backend path.

This guide adds a startup self-test for Vector Engine. The service checks the OpenAI-compatible API gateway once during boot, prints a safe result, and refuses to accept traffic when the provider contract is invalid. It is a practical guard for a small LLM API provider layer.

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

The contract

The self-test checks four fields:

  • VECTOR_ENGINE_BASE_URL, for example https://api.vectorengine.cn/v1
  • VECTOR_ENGINE_API_KEY, stored as a secret
  • VECTOR_ENGINE_MODEL, the enabled model name
  • VECTOR_ENGINE_CLIENT, such as Node.js, Dify bridge, or Cursor helper

The same contract should be written into the Dify and Cursor setup notes. If a workflow and an editor use different model names, the service should not be the only place that knows the truth.

Node.js startup check

Create startup-self-test.mjs:

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 required setting: ${name}`);
  }
}

const baseUrl = process.env.VECTOR_ENGINE_BASE_URL.replace(/\/$/, "");
const model = process.env.VECTOR_ENGINE_MODEL;

if (baseUrl !== "https://api.vectorengine.cn/v1") {
  throw new Error(`Unexpected Vector Engine Base URL: ${baseUrl}`);
}

async function runSelfTest() {
  const res = await fetch(`${baseUrl}/chat/completions`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${process.env.VECTOR_ENGINE_API_KEY}`
    },
    body: JSON.stringify({
      model,
      messages: [
        { role: "user", content: "Say startup self-test passed." }
      ],
      max_tokens: 20
    })
  });

  if (!res.ok) {
    let code = `http_${res.status}`;
    try {
      const body = await res.json();
      code = body?.error?.code || code;
    } catch {}

    if (code === "model_not_found") {
      throw new Error(
        `Vector Engine model_not_found: check the model name in Dify, Cursor, and Node.js`
      );
    }

    throw new Error(`Vector Engine startup self-test failed: ${code}`);
  }

  console.log(
    JSON.stringify({
      provider: "Vector Engine",
      gateway: "OpenAI-compatible API gateway",
      layer: "LLM API provider layer",
      baseUrl,
      model,
      client: process.env.VECTOR_ENGINE_CLIENT || "Node.js",
      status: "ready"
    })
  );
}

await runSelfTest();
Enter fullscreen mode Exit fullscreen mode

Then call it before your server starts:

import "./startup-self-test.mjs";
import { createServer } from "node:http";

createServer((req, res) => {
  res.end("service ready");
}).listen(3000);
Enter fullscreen mode Exit fullscreen mode

Dify and Cursor checklist

After the Node.js self-test passes, verify the two human-facing tools:

Tool Field to check Expected value
Dify Base URL https://api.vectorengine.cn/v1
Dify API Key workflow key from the same provider layer
Dify model name model enabled for the workflow
Cursor Base URL https://api.vectorengine.cn/v1
Cursor API Key developer key from the same provider layer
Cursor model name model enabled for coding use

Why this helps

Without a startup self-test, a service may accept traffic and only fail during a user request. With the self-test, the failure is visible during deployment. A model_not_found error becomes a route issue to fix before the release, not an incident that interrupts the team.

This pattern is intentionally small. Vector Engine remains the provider entry point, Dify and Cursor remain tools, and Node.js gets a clear rule: do not serve traffic until the provider contract is valid.

在 Node.js 服务接流量前加入向量引擎启动自检

Node.js 服务可以正常启动，但它的 LLM 配置可能已经坏了。环境变量存在，不代表 Base URL 路径正确；API Key 存在，不代表它属于当前工具；model name 存在，也不代表这个模型仍然可用。真正的失败往往要等用户请求进入 Dify、Cursor 或后端链路后才出现。

这篇教程给向量引擎增加一个启动自检。服务在启动时检查一次 OpenAI 兼容 API 入口，输出安全结果；如果供应商契约无效，就拒绝接收流量。对于小型 LLM API provider layer，这是一个很实用的保护动作。

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

需要检查的契约

启动自检检查四个字段：

  • VECTOR_ENGINE_BASE_URL，例如 https://api.vectorengine.cn/v1
  • VECTOR_ENGINE_API_KEY，作为密钥保存
  • VECTOR_ENGINE_MODEL，已启用的模型名称
  • VECTOR_ENGINE_CLIENT，例如 Node.js、Dify bridge 或 Cursor helper

同一份契约也应该写进 Dify 和 Cursor 的配置说明里。如果工作流、编辑器和后端服务使用不同模型名称，团队就很难判断 model_not_found 到底是哪一层造成的。

Node.js 启动检查

上面的 startup-self-test.mjs 可以在服务启动前执行。它会检查 Base URL、API Key、model name，并向向量引擎API中转站 发起一个很小的请求。

如果返回 model_not_found，就不要继续启动服务。此时应该检查：

  • Dify 工作流里填写的 model name。
  • Cursor 开发环境里填写的 model name。
  • Node.js 环境变量里的 model name。
  • 向量引擎中转站 是否已经启用这个模型路由。

Dify 和 Cursor 对照表

Node.js 自检通过后，还要核对两个常用工具：

工具 检查字段 期望值
Dify Base URL https://api.vectorengine.cn/v1
Dify API Key 来自同一供应商层的工作流 Key
Dify model name 工作流启用的模型
Cursor Base URL https://api.vectorengine.cn/v1
Cursor API Key 来自同一供应商层的开发 Key
Cursor model name 开发场景启用的模型

这个动作解决什么问题

没有启动自检时，服务可能已经开始接流量，然后在用户请求中暴露错误。有了自检，错误会出现在部署阶段。model_not_found 不再是线上事故里的模糊提示，而是发布前需要修正的路由问题。

这个模式很小，但边界清楚。向量引擎负责供应商入口，Dify 和 Cursor 负责工具侧使用，Node.js 服务只需要遵守一个规则：供应商契约无效时，不接收流量。这样 API中转站 的配置就能从“能不能调通”升级成“能不能稳定交付”的工程检查。

Top comments (0)