여러 도구가 동일한 LLM 경로를 공유할 때, 요청 실패의 원인이 단 하나의 필드만으로 설명되는 경우는 드뭅니다. Dify의 Base URL은 올바를 수 있고, Cursor의 API Key는 최신 상태일 수 있지만, 단 하나의 헤더, 모델 이름(model name), 또는 환경 변수(environment variable)가 드리프트(drift)되어 Node.js 서비스가 여전히 실패할 수 있습니다. 이 튜토리얼에서는 Vector Engine을 OpenAI 호환 API 게이트웨이(gateway)로 사용하며, 도구들이 동일한 경로에 연결되기 전에 작은 헤더 드리프트 프로브(header drift probe)를 구축합니다.

목표는 비밀 정보(secrets)를 로그에 남기는 것이 아닙니다. 목표는 어떤 도구가 요청을 보냈는지, 어떤 Base URL 형태를 사용했는지, 어떤 모델 이름을 요청했는지, 그리고 API Key 자체가 출력되지 않으면서 키가 존재했는지 여부를 팀에 알려주는 작은 영수증(receipt)을 만드는 것입니다. 이 영수증은 model_not_found 에러가 발생했을 때 모든 팀원이 다른 도구가 원인이라고 생각하는 상황에서 유용하게 쓰입니다.

설정 계약 (Configuration contract)

LLM API 제공자 계층을 호출할 모든 도구에 대해 하나의 공유된 계약(contract)을 사용하세요:

Base URL: https://api.vectorengine.cn/v1
API Key: 도구의 비밀 저장소(secret store) 또는 환경 변수(environment variable)에 보관
model name: 계정에 활성화된 정확한 경로 이름
...

Dify, Cursor, Node.js는 동일한 사용자 인터페이스(user interface)를 노출하지 않지만, 여전히 동일한 계약을 공유할 수 있습니다. Dify는 모델 제공자 설정(model provider settings)에 제공자 Base URL과 모델을 유지합니다. Cursor는 모델 설정(model configuration)에 Base URL과 API Key를 유지합니다. Node.js는 환경 변수(environment variables)에서 이를 읽고 가벼운 도구 라벨(tool label)을 추가합니다.

작은 Node.js 프로브 (A small Node.js probe)

vector-engine-header-probe.mjs를 생성합니다:

const baseURL = process.env.VECTOR_ENGINE_BASE_URL || "https://api.vectorengine.cn/v1";
const apiKey = process.env.VECTOR_ENGINE_API_KEY;
const model = process.env.VECTOR_ENGINE_MODEL || "replace-with-enabled-model";
...

한 번에 하나의 도구 라벨로 실행합니다:

VECTOR_ENGINE_BASE_URL=https://api.vectorengine.cn/v1 \
VECTOR_ENGINE_API_KEY=sk-your-key \
VECTOR_ENGINE_MODEL=your-enabled-model \
...

도구 간에 비교해야 할 사항

Node.js만 실패한다면 환경 변수(environment variables)와 요청 경로(request path)를 점검하세요. Dify와 Cursor가 동일한 model_not_found 오류로 실패한다면, 키를 교체하기 전에 Vector Engine의 모델 경로(model route)를 확인하세요. 한 도구는 성공하고 다른 도구가 401 또는 403 오류로 실패한다면, API 키의 권한 범위(API Key scope)와 계정 소유권(account ownership)을 비교하세요.

Dify 및 Cursor 설정 참고 사항

Dify의 경우, OpenAI 호환 제공자(OpenAI-compatible provider) 영역에 동일한 Base URL을 붙여넣고, 모델 이름이 Node.js 프로브(probe)가 사용한 경로와 일치하는지 확인하세요. 복사된 표시 이름(display name)이 API 모델 이름과 항상 일치하는 것은 아닙니다.

Cursor의 경우, 모델 제공자 설정(model provider configuration)에 Base URL과 API 키를 유지하세요. 그런 다음 프로젝트 컨텍스트(project context)에 의존하지 않는 작은 프롬프트를 하나 실행하세요. 목표는 제공자 도달 가능성(provider reachability)과 애플리케이션 동작(application behavior)을 분리하는 것입니다.

Node.js의 경우, 프로브를 버전 관리(version control)에 유지하되 API 키는 절대 커밋하지 마세요. 팀들은 로컬 스크립트, Dify 워크스페이스, Cursor 프로젝트가 서로 다른 사람들에 의해 변경되었기 때문에 사고가 발생한 후에야 드리프트(drift)를 발견하는 경우가 많습니다.

model_not_found를 위한 분류(Triage) 테이블

이렇게 하면 LLM API 제공자 계층(LLM API provider layer)을 안정적으로 유지할 수 있습니다. Vector Engine은 도구들 뒤에 위치하지만, 팀은 여전히 각 호출자가 사용하는 정확한 설정 표면(configuration surface)을 관리해야 합니다.

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

Dify, Cursor, Node.js가 Vector Engine을 공유하기 전 헤더 드리프트(Trace Header Drift) 추적하기

여러 도구가 동일한 LLM 경로(route)를 공유할 때, 요청 실패는 대개 단일 필드 때문이 아닙니다. Dify의 Base URL은 올바를 수 있고, Cursor의 API 키는 유효할 수 있지만, Node.js 서비스는 요청 헤더(request header), 모델 이름 또는 환경 변수 드리프트로 인해 여전히 실패할 수 있습니다. 본문에서는 Vector Engine을 OpenAI 호환 API 게이트웨이(OpenAI-compatible API gateway) 및 LLM API 제공자 계층(LLM API provider layer)으로 간주하고, 먼저 소규모 요청 헤더 드리프트 프로브(request header drift probe)를 수행한 뒤 여러 도구가 동일한 경로를 공유하도록 구성하는 방법을 다룹니다.

목표는 키(key)를 기록하는 것이 아닙니다. 목표는 요청이 어떤 도구에서 왔는지, 어떤 Base URL 형식을 사용했는지, 어떤 model name을 요청했는지, 그리고 API Key가 존재하는지 여부를 명시하되 키 자체는 출력하지 않는 작은 영수증을 생성하는 것입니다. model_not_found가 발생했을 때, 이 영수증은 각 팀이 문제가 다른 곳에서 발생했다고 오해하는 상황을 방지해 줍니다.

구성 계약 (Configuration Contract)

벡터 엔진 (Vector Engine) API 중계소(proxy)를 호출하는 모든 도구는 먼저 동일한 계약을 맞출 수 있습니다:

Base URL: https://api.vectorengine.cn/v1
API Key: 도구의 키 영역 또는 환경 변수(environment variable)에 배치
model name: 계정에서 이미 활성화된 정확한 라우팅 이름
...

Dify, Cursor, Node.js는 인터페이스가 다르지만, 구성 계약은 일관되게 유지할 수 있습니다. Dify는 모델 공급자 설정에서 Base URL과 모델을 저장합니다. Cursor는 모델 설정에서 Base URL과 API Key를 저장합니다. Node.js는 환경 변수에서 이 값들을 읽어오며, 가벼운 도구 태그(tool tag)를 함께 전달합니다.

소형 Node.js 프로브 (Probe)

vector-engine-header-probe.mjs를 생성합니다:

const baseURL = process.env.VECTOR_ENGINE_BASE_URL || "https://api.vectorengine.cn/v1";
const apiKey = process.env.VECTOR_ENGINE_API_KEY;
const model = process.env.VECTOR_ENGINE_MODEL || "replace-with-enabled-model";
...

도구 태그별로 각각 실행합니다:

VECTOR_ENGINE_BASE_URL=https://api.vectorengine.cn/v1 \
VECTOR_ENGINE_API_KEY=sk-your-key \
VECTOR_ENGINE_MODEL=your-enabled-model \
...

도구 간 필드 비교

Node.js만 실패한다면, 먼저 환경 변수와 요청 경로를 확인하십시오. 만약 Dify와 Cursor 모두 model_not_found를 반환한다면, 키를 교체하기 전에 벡터 엔진 중계소의 모델 라우팅을 먼저 점검하십시오. 특정 도구는 성공하는데 다른 도구가 401 또는 403을 반환한다면, API Key의 권한 범위와 계정 소유권을 비교하십시오.

Dify 및 Cursor 구성 팁

Dify에서는 동일한 Base URL을 OpenAI-compatible provider 영역에 입력하고, 모델 이름이 Node.js 프로브에서 사용하는 라우팅 이름과 일치하는지 확인하십시오. 표시되는 이름(display name)이 반드시 API model name과 일치하는 것은 아닙니다.

Cursor에서는 Base URL과 API Key를 모델 공급자 설정에 넣으십시오. 그런 다음 프로젝트 컨텍스트에 의존하지 않는 작은 프롬프트를 실행하여, 공급자 도달 가능성(reachability)과 애플리케이션 동작을 분리하여 테스트하십시오.

Node.js에서는 프로브를 저장소(repository)에 넣되, API Key는 커밋하지 마십시오. 많은 팀이 사고가 발생한 후에야 로컬 스크립트, Dify 워크스페이스, Cursor 프로젝트가 각각 서로 다른 사람에 의해 수정되었다는 사실을 발견하곤 합니다.

model_not_found 점검표

이렇게 함으로써 LLM API provider layer를 안정적으로 유지할 수 있습니다. 벡터 엔진은 도구 뒤에 위치하지만, 각 호출자가 사용하는 구체적인 구성 면은 여전히 팀 스스로 책임져야 합니다.

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