Vector Engine이 여러 내부 도구를 위한 공유 OpenAI 호환 API 게이트웨이가 될 때, 어려운 점은 HTTP 요청 그 자체인 경우가 거의 없습니다. 진짜 어려운 점은 각 도구가 동일한 Base URL, API Key 소스, 모델 이름, 타임아웃(timeout), 그리고 에러 기대치(error expectations)를 일관되게 유지하도록 하는 것입니다. Dify는 값을 프로바이더 양식(provider form)에 저장할 수 있고, Cursor는 이를 로컬 설정 파일에 보관할 수 있으며, Node.js 서비스는 환경 변수(environment variables)에서 이를 읽어올 수 있습니다.

이 튜토리얼에서는 Node.js를 사용하여 작은 도구 프로필 리졸버(tool profile resolver)를 구축합니다. 이 도구는 프롬프트(prompts)를 전송하지 않습니다. 트래픽이 LLM API 프로바이더 계층을 통과하기 전에 모든 클라이언트에 대해 정제된 프로필을 출력합니다. 목표는 개발자가 운영 환경에서 model_not_found 오류를 마주하기 전에 설정 드리프트(configuration drift)를 포착하는 것입니다.

프로필 형태 (The profile shape)

도구당 하나의 프로필을 사용하세요. 출력 결과에 비밀 값(secrets)이 포함되지 않도록 하세요.

const profiles = {
  dify: {
    tool: "Dify",
...

OpenAI 호환 클라이언트의 경우, Base URL은 프로바이더의 베이스가 되어야 합니다:

VECTOR_ENGINE_BASE_URL=https://api.vectorengine.cn/v1

Base URL을 기대하는 필드에 전체 chat-completions 엔드포인트를 붙여넣지 마세요. 클라이언트 앱이 또 다른 경로 세그먼트(path segment)를 추가하기 때문에, 그러한 실수는 종종 혼란스러운 404 오류나 model_not_found 메시지를 생성합니다.

리졸버 (The resolver)

리졸버는 누락된 필드, 안전하지 않은 경로, 그리고 모델 이름의 일관성을 확인합니다.

function normalizeBaseURL(value) {
  if (!value) return "";
  return value.replace(//+$/, "");
...

이 출력 결과는 API Key의 값(value)이 아닌 변수명(variable name)을 보여주므로, 내부 티켓(internal ticket)에 붙여넣기에 안전합니다.

Dify와 Cursor에서 비교해야 할 사항

리졸버 출력값을 체크리스트로 사용하세요:

model_not_found 오류가 나타날 때, 즉시 키를 교체하지 마세요. Dify, Cursor, 그리고 Node.js 서비스가 동일한 모델 이름과 동일한 Vector Engine 경로를 사용하고 있는지 확인하십시오. 잘못 매칭된 모델 필드를 수정하는 것이 무작정 제공자(provider)를 변경하는 것보다 훨씬 쉽습니다.

스모크 요청(smoke request) 하나 추가하기

리졸버(resolver)를 통과한 후, Node.js 서비스 프로필에서 짧은 스모크 요청(smoke request)을 실행하세요.

async function smoke() {
  const baseURL = normalizeBaseURL(process.env.VECTOR_ENGINE_BASE_URL);
  const response = await fetch(`${baseURL}/chat/completions`, {
...

이 스모크 요청은 작게 유지하십시오. 리졸버는 설정을 확인하고, 스모크 요청은 OpenAI 호환 API 게이트웨이(API gateway)를 통하는 경로를 확인합니다.

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

요약

도구 설정이 명시적일 때 공유 LLM API 제공자 계층(provider layer)을 운영하기가 더 쉽습니다. Dify, Cursor, 그리고 Node.js 서비스가 Vector Engine을 공유하기 전에, 리졸브된 기본 URL(Base URL), API 키 소스, 모델 이름, 그리고 타임아웃(timeout)을 출력하십시오. 그 작은 단계가 model_not_found를 모호한 사용자 불만에서 구체적인 설정 차이(configuration diff)로 바꿔줍니다.

Dify, Cursor, Node.js가 Vector Engine을 공유하기 전, 도구 설정 리졸버(Tool Profile Resolver) 작성하기

Vector Engine이 여러 내부 도구에서 공용으로 사용하는 OpenAI 호환 엔드포인트가 될 때, 진짜 문제는 HTTP 요청 자체가 아니라 각 도구가 동일한 Base URL, API 키 소스, 모델 이름, 타임아웃 설정 및 오류 기대치를 정직하게 사용하고 있는지 여부입니다. Dify는 설정을 모델 제공자 양식에 둘 수 있고, Cursor는 로컬 설정에 둘 수 있으며, Node.js 서비스는 보통 환경 변수에서 읽어옵니다.

이 튜토리얼에서는 Node.js를 사용하여 도구 설정 리졸버(tool configuration resolver)를 작성합니다. 이 리졸버는 비즈니스 프롬프트를 전송하지 않고, 트래픽이 LLM API 제공자 계층(LLM API provider layer)에 진입하기 전에 각 클라이언트의 비식별화된 설정을 출력합니다. 목표는 개발자가 model_not_found를 마주하기 전에 설정 드리프트(configuration drift)를 발견하는 것입니다.

설정 구조

각 도구는 프로필(profile)을 유지하며, 키의 평문은 출력하지 않습니다.

const profiles = {
  dify: {
    tool: "Dify",
...

OpenAI 호환 클라이언트의 경우, Base URL은 서비스의 기본 주소여야 합니다. 예시:

VECTOR_ENGINE_BASE_URL=https://api.vectorengine.cn/v1

Base URL만 필요한 필드에 전체 chat-completions 인터페이스 주소를 입력하지 마세요. 많은 404 또는 model_not_found 오류는 사실 도구가 경로를 자동으로 추가하면서 경로가 중복되어 발생합니다.

리졸버 코드

리졸버(Resolver)는 누락된 필드, 잘못된 경로, 그리고 모델 이름의 일관성을 검사합니다.

function normalizeBaseURL(value) {
  if (!value) return "";
  return value.replace(//+$/, "");
...

출력 결과는 내부 티켓(Internal Ticket)에 붙여넣을 수 있습니다. API Key의 실제 값은 노출하지 않고 변수명만 보여주기 때문입니다.

Dify와 Cursor에서 대조해야 할 사항

리졸버의 출력값을 체크리스트로 활용할 수 있습니다:

model_not_found 오류가 발생했을 때 즉시 키(Key)를 교체하지 마세요. 먼저 Dify, Cursor, 그리고 Node.js 서비스가 동일한 모델 이름을 사용하는지, 그리고 동일한 벡터 엔진(Vector Engine) 라우트를 사용하는지 확인해야 합니다. 모델 필드 불일치는 무작정 공급업체를 바꾸는 것보다 훨씬 처리하기 쉽습니다.

스모크 테스트(Smoke Test) 추가

설정이 통과되면, Node.js 서비스 프로필(profile)을 사용하여 매우 짧은 스모크 요청(smoke request)을 보냅니다.

async function smoke() {
  const baseURL = normalizeBaseURL(process.env.VECTOR_ENGINE_BASE_URL);
  const response = await fetch(`${baseURL}/chat/completions`, {
...

벡터 엔진(Vector Engine) API 프록시는 여러 도구의 엔트리를 통합 관리하기에 적합하지만, 전제 조건은 설정값이 다시 읽힐 수 있어야 한다는 점입니다. 벡터 엔진 프록시는 모든 도구를 블랙박스(Black box)로 만드는 것이 아니라, 팀이 API 프록시의 Base URL, 키(Key) 출처, 모델명, 그리고 오류 책임 소재를 명확히 정의할 수 있도록 하는 것입니다.

등록 주소: https://api.vectorengine.cn/register?aff=Igym

요약

공유된 LLM API 프로바이더(Provider) 레이어는 설정이 명시적일 때만 운영하기 쉽습니다. Dify, Cursor, 그리고 Node.js 서비스가 벡터 엔진을 공유하기 전에, 먼저 파싱된 Base URL, API Key 출처, 모델 이름, 그리고 타임아웃(Timeout) 설정을 출력해 보세요. 이렇게 하면 model_not_found는 더 이상 모호한 불만이 아니라, 구체적인 설정 차이를 찾아낼 수 있는 엔지니어링 신호가 됩니다.