DEV Community

Jia
Jia

Posted on

Choose the Right Vector Engine BASE_URL for Dify, Cursor, and Node.js

#javascript #webdev #programming #ai

When a client fails to call Vector Engine, many developers start by checking the API Key or the model name. That is reasonable, but there is another common source of confusion: different clients may expect different BASE_URL shapes.

For Vector Engine, do not assume every tool wants the same endpoint string. Some clients expect only the host, some expect /v1, and some expect the full chat completions path. If Dify, Cursor, or a custom Node.js script returns a strange error, the BASE_URL value should be part of the early troubleshooting pass.

This DEV tutorial shows a practical way to test Vector Engine as an OpenAI-compatible API gateway without mixing up Base URL, API Key, model name, and model_not_found errors inside the LLM API provider layer.

Interface configuration

Use these optional BASE_URL values when configuring a client:

https://api.vectorengine.cn
https://api.vectorengine.cn/v1
https://api.vectorengine.cn/v1/chat/completions
Enter fullscreen mode Exit fullscreen mode

Note: different clients may require different BASE_URL values. If one value does not work, try the next value in the list instead of immediately changing the API Key or model name.

Why different clients need different values

OpenAI-compatible clients do not all build request URLs the same way.

Client behavior Expected BASE_URL shape Example final request
Client appends /v1/chat/completions Host only https://api.vectorengine.cn/v1/chat/completions
Client appends /chat/completions /v1 path https://api.vectorengine.cn/v1/chat/completions
Client sends the URL as provided Full endpoint https://api.vectorengine.cn/v1/chat/completions

This is why a single hard rule can be misleading. The correct value depends on how the caller constructs the final request.

Suggested configuration order

When connecting Dify, Cursor, or a Node.js client to Vector Engine, test in this order:

1. https://api.vectorengine.cn
2. https://api.vectorengine.cn/v1
3. https://api.vectorengine.cn/v1/chat/completions
Enter fullscreen mode Exit fullscreen mode

After each attempt, keep the API Key and model name unchanged. Only change the BASE_URL. That makes the test useful because you are isolating one variable at a time.

Node.js probe

The following Node.js script lets you test all three BASE_URL candidates without exposing your API Key in logs.

const candidates = [
  "https://api.vectorengine.cn",
  "https://api.vectorengine.cn/v1",
  "https://api.vectorengine.cn/v1/chat/completions"
];

const apiKey = process.env.VECTOR_ENGINE_API_KEY;
const model = process.env.VECTOR_ENGINE_MODEL || "gpt-4.1-mini";

function buildUrl(baseUrl) {
  if (baseUrl.endsWith("/chat/completions")) {
    return baseUrl;
  }

  if (baseUrl.endsWith("/v1")) {
    return `${baseUrl}/chat/completions`;
  }

  return `${baseUrl}/v1/chat/completions`;
}

async function testBaseUrl(baseUrl) {
  const url = buildUrl(baseUrl);

  const response = await fetch(url, {
    method: "POST",
    headers: {
      "content-type": "application/json",
      "authorization": `Bearer ${apiKey}`
    },
    body: JSON.stringify({
      model,
      messages: [
        { role: "user", content: "Return the word ready." }
      ],
      temperature: 0
    })
  });

  const payload = await response.json().catch(() => ({}));
  const errorCode = payload?.error?.code || payload?.code || null;

  return {
    baseUrl,
    finalUrl: url,
    status: response.status,
    errorCode,
    ok: response.ok
  };
}

for (const baseUrl of candidates) {
  const result = await testBaseUrl(baseUrl);
  console.log(JSON.stringify(result));
}
Enter fullscreen mode Exit fullscreen mode

Use this as a local probe before changing Dify or Cursor settings. If one candidate returns a successful response, keep that client on the working BASE_URL shape.

Dify configuration notes

For Dify, start with:

https://api.vectorengine.cn
Enter fullscreen mode Exit fullscreen mode

If the provider setup fails, try:

https://api.vectorengine.cn/v1
Enter fullscreen mode Exit fullscreen mode

If Dify expects a full endpoint in your specific provider form, try:

https://api.vectorengine.cn/v1/chat/completions
Enter fullscreen mode Exit fullscreen mode

Keep the API Key and model name stable while testing. If you change all three at once, you will not know which setting fixed the problem.

Cursor configuration notes

Cursor may behave differently depending on how the provider is configured. If the model provider form appends the OpenAI-compatible path internally, the host-only value may work. If it expects an API root, /v1 may be the right value.

Use the same test order:

https://api.vectorengine.cn
https://api.vectorengine.cn/v1
https://api.vectorengine.cn/v1/chat/completions
Enter fullscreen mode Exit fullscreen mode

After the BASE_URL works, record the model name and API Key owner in the project notes. This keeps local Cursor experiments from becoming hidden production assumptions.

Node.js configuration notes

For Node.js, be explicit about what your client library expects.

If your library wants a provider root, use:

VECTOR_ENGINE_BASE_URL=https://api.vectorengine.cn
Enter fullscreen mode Exit fullscreen mode

If your library wants an OpenAI-compatible API root, use:

VECTOR_ENGINE_BASE_URL=https://api.vectorengine.cn/v1
Enter fullscreen mode Exit fullscreen mode

If your code sends the request directly without appending a path, use:

VECTOR_ENGINE_BASE_URL=https://api.vectorengine.cn/v1/chat/completions
Enter fullscreen mode Exit fullscreen mode

The important part is to avoid double-appending paths. A final URL like /v1/chat/completions/chat/completions usually means the client and configuration are both adding the endpoint path.

model_not_found troubleshooting

Do not treat every failed request as model_not_found. Separate the checks:

Symptom Check first
Network or 404-like failure Try the next BASE_URL candidate
401 or 403 Check API Key value and scope
model_not_found Check the model name and route availability
Empty or unexpected response Check how the client parses the response

This makes the LLM API provider layer easier to operate. Vector Engine can route model access for multiple tools, but each client still needs the right URL shape.

Registration

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

Closing note

The practical rule is simple: when configuring Vector Engine, test the three supported BASE_URL shapes before changing other settings. Dify, Cursor, and Node.js may each expect a different value. Keep the API Key and model name stable during the test, then handle real model_not_found errors only after the request path is correct.

为 Dify、Cursor 和 Node.js 选择正确的向量引擎 BASE_URL

当客户端调用向量引擎失败时，很多开发者会先检查 API Key 或模型名称。这是合理的，但还有一个常见混淆来源：不同客户端可能需要不同形态的 BASE_URL。

对 Vector Engine 来说，不要假设每个工具都需要同一个接口地址。有些客户端只需要主机地址，有些需要 /v1，有些则需要完整的 chat completions 路径。如果 Dify、Cursor 或自定义 Node.js 脚本返回奇怪错误，BASE_URL 应该进入早期排查。

这篇 DEV 教程会说明如何把向量引擎作为 OpenAI-compatible API gateway 来测试，同时避免把 Base URL、API Key、模型名称和 model_not_found 错误混在 LLM API provider layer 里。

接口配置

配置客户端时，可以使用下面这些可选 BASE_URL：

https://api.vectorengine.cn
https://api.vectorengine.cn/v1
https://api.vectorengine.cn/v1/chat/completions
Enter fullscreen mode Exit fullscreen mode

注意：不同客户端可能需要使用不同的 BASE_URL。如果一个地址不可用，建议依次尝试以上地址，而不是立刻修改 API Key 或模型名称。

为什么不同客户端需要不同地址

OpenAI-compatible 客户端并不总是用同一种方式拼接请求 URL。

客户端行为 预期 BASE_URL 形态 最终请求示例
客户端自动追加 /v1/chat/completions 只填主机地址 https://api.vectorengine.cn/v1/chat/completions
客户端自动追加 /chat/completions 填 /v1 路径 https://api.vectorengine.cn/v1/chat/completions
客户端按原样发送 URL 填完整接口地址 https://api.vectorengine.cn/v1/chat/completions

这就是为什么单一规则容易误导。正确地址取决于调用方如何构造最终请求。

建议测试顺序

把 Dify、Cursor 或 Node.js 客户端接入向量引擎时，按这个顺序测试：

1. https://api.vectorengine.cn
2. https://api.vectorengine.cn/v1
3. https://api.vectorengine.cn/v1/chat/completions
Enter fullscreen mode Exit fullscreen mode

每次尝试后，保持 API Key 和模型名称不变，只修改 BASE_URL。这样测试才有意义，因为你一次只隔离一个变量。

Node.js 探针

下面的 Node.js 脚本可以测试三个 BASE_URL 候选值，同时不会把 API Key 打进日志。

const candidates = [
  "https://api.vectorengine.cn",
  "https://api.vectorengine.cn/v1",
  "https://api.vectorengine.cn/v1/chat/completions"
];

const apiKey = process.env.VECTOR_ENGINE_API_KEY;
const model = process.env.VECTOR_ENGINE_MODEL || "gpt-4.1-mini";

function buildUrl(baseUrl) {
  if (baseUrl.endsWith("/chat/completions")) {
    return baseUrl;
  }

  if (baseUrl.endsWith("/v1")) {
    return `${baseUrl}/chat/completions`;
  }

  return `${baseUrl}/v1/chat/completions`;
}

async function testBaseUrl(baseUrl) {
  const url = buildUrl(baseUrl);

  const response = await fetch(url, {
    method: "POST",
    headers: {
      "content-type": "application/json",
      "authorization": `Bearer ${apiKey}`
    },
    body: JSON.stringify({
      model,
      messages: [
        { role: "user", content: "Return the word ready." }
      ],
      temperature: 0
    })
  });

  const payload = await response.json().catch(() => ({}));
  const errorCode = payload?.error?.code || payload?.code || null;

  return {
    baseUrl,
    finalUrl: url,
    status: response.status,
    errorCode,
    ok: response.ok
  };
}

for (const baseUrl of candidates) {
  const result = await testBaseUrl(baseUrl);
  console.log(JSON.stringify(result));
}
Enter fullscreen mode Exit fullscreen mode

在修改 Dify 或 Cursor 配置前，可以先用这个本地探针测试。如果某个候选地址返回成功，就让对应客户端使用这个 BASE_URL 形态。

Dify 配置注意点

对 Dify，先尝试：

https://api.vectorengine.cn
Enter fullscreen mode Exit fullscreen mode

如果提供方配置失败，再尝试：

https://api.vectorengine.cn/v1
Enter fullscreen mode Exit fullscreen mode

如果你的 Dify 提供方表单需要完整接口地址，再尝试：

https://api.vectorengine.cn/v1/chat/completions
Enter fullscreen mode Exit fullscreen mode

测试过程中保持 API Key 和模型名称稳定。如果三个配置一起改，你就无法判断到底是哪一项修复了问题。

Cursor 配置注意点

Cursor 的行为可能取决于提供方配置方式。如果模型提供方表单内部会追加 OpenAI-compatible 路径，只填主机地址可能可用。如果它期望 API root，那么 /v1 可能更合适。

仍然使用同样的测试顺序：

https://api.vectorengine.cn
https://api.vectorengine.cn/v1
https://api.vectorengine.cn/v1/chat/completions
Enter fullscreen mode Exit fullscreen mode

当 BASE_URL 可用后，把模型名称和 API Key 负责人记录到项目说明中。这样可以避免本地 Cursor 实验变成隐藏的生产假设。

Node.js 配置注意点

对 Node.js，要明确你的客户端库期望什么。

如果客户端库需要提供方根地址，使用：

VECTOR_ENGINE_BASE_URL=https://api.vectorengine.cn
Enter fullscreen mode Exit fullscreen mode

如果客户端库需要 OpenAI-compatible API root，使用：

VECTOR_ENGINE_BASE_URL=https://api.vectorengine.cn/v1
Enter fullscreen mode Exit fullscreen mode

如果你的代码不会追加路径，而是直接发送请求，使用：

VECTOR_ENGINE_BASE_URL=https://api.vectorengine.cn/v1/chat/completions
Enter fullscreen mode Exit fullscreen mode

关键是避免重复追加路径。如果最终 URL 变成 /v1/chat/completions/chat/completions，通常说明客户端和配置都在追加接口路径。

model_not_found 排查

不要把所有失败请求都当作 model_not_found。可以分开检查：

现象 先检查什么
网络失败或类似 404 尝试下一个 BASE_URL 候选值
401 或 403 检查 API Key 值和权限范围
model_not_found 检查模型名称和路由可用性
空响应或响应形态异常 检查客户端如何解析响应

这样能让 LLM API provider layer 更容易运维。向量引擎可以为多个工具路由模型访问，但每个客户端仍然需要正确的 URL 形态。

注册

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

结语

实际规则很简单：配置向量引擎时，先测试三个支持的 BASE_URL 形态，再修改其他设置。Dify、Cursor 和 Node.js 可能各自需要不同的值。测试期间保持 API Key 和模型名称稳定，等请求路径正确后，再处理真正的 model_not_found 问题。对向量引擎API中转站、向量引擎中转站和 API中转站 来说，这种排查方式能减少误判，也能让接口接入更稳。

::inbox-item{title="Complete DEV article provided" summary="BASE_URL matrix draft pasted for publishing"}

Top comments (0)