여러 도구가 하나의 OpenAI 호환 API 게이트웨이를 공유할 때, 설정에서 가장 취약한 부분은 종종 게이트웨이 자체가 아닙니다. 그것은 각 도구가 생각하는 모델 이름, Base URL이 가리키는 곳, 그리고 어떤 API Key가 해당 경로를 사용할 권한이 있는지 사이의 작은 간극입니다.

이 튜토리얼은 그 간극을 줄이는 실질적인 방법을 보여줍니다. 저장소(repository)에 작은 모델 경로 매니페스트(model route manifest)를 유지하고, 이를 Node.js로 검증한 다음, 동일한 값들을 Dify와 Cursor에 복사하는 방식입니다. Vector Engine은 LLM API 제공자 계층에 위치할 수 있지만, 모든 클라이언트는 여전히 다음 세 가지 값이 일치해야 합니다:

• Base URL
• API Key
• 모델 이름 (model name)

경로 매니페스트 (Route manifest)

vector-engine-routes.json이라는 이름의 파일을 생성합니다:

{
  "provider": "Vector Engine",
  "baseUrl": "https://api.vectorengine.cn/v1",
...

이 파일은 비밀 정보를 노출하기 위한 것이 아닙니다. API Key는 환경 변수(environment variable)에 보관하세요:

export VECTOR_ENGINE_API_KEY="your_key_here"

Node.js 검증 스크립트 (Node.js validation script)

check-vector-engine-route.mjs를 추가합니다:

import fs from "node:fs/promises";

const manifest = JSON.parse(
...

도구 설정을 변경하기 전에 실행하세요:

node check-vector-engine-route.mjs

만약 이 스크립트가 model_not_found로 실패한다면, 해당 에러를 라우팅 힌트로 취급하세요. API Key는 유효할 수 있지만 모델 이름, 경로 권한(route permission), 또는 Base URL이 잘못되었을 수 있습니다.

동일한 값을 Dify에 복사하기

Dify에서 제공자(provider)를 OpenAI 호환 엔드포인트(OpenAI-compatible endpoint)로 추가합니다:

• Base URL: https://api.vectorengine.cn/v1
• API Key: Vector Engine을 위해 저장된 것과 동일한 비밀 값을 사용합니다.
• 모델 이름 (model name): 매니페스트에서 model 값을 정확히 복사합니다.

매니페스트를 함께 업데이트하지 않는 한, Dify에서 모델 필드를 번역, 축소 또는 이름을 변경하지 마세요. 저장소에 있는 default-chat이라는 이름의 경로는 구체적인 모델 이름으로 매핑될 수 있지만, Dify는 여전히 제공자 설정에 입력한 모델 문자열을 전송합니다.

동일한 값을 Cursor에 복사하기

Cursor 또한 유사한 리스크 프로필을 가지고 있습니다. 커스텀 제공자(provider) URL과 키를 수락할 수는 있지만, Vector Engine이 라우팅할 수 있는 모델 이름이 여전히 필요합니다.

권장 확인 사항:

만약 Cursor가 model_not_found를 반환한다면, 키를 교체하거나 코드를 변경하기 전에 표시된 모델 이름을 매니페스트(manifest)와 비교하십시오.

매니페스트가 도움이 되는 이유

공유된 LLM API 제공자(provider) 계층은 애플리케이션 팀의 속도를 높여주어야 하지만, 이는 설정이 가시적으로 유지될 때만 가능합니다. 매니페스트는 Dify 워크플로, Cursor 설정 또는 Node.js 서비스가 동일한 Vector Engine 경로를 사용하기 시작하기 전에 검토자가 확인할 수 있는 작은 파일을 제공합니다.

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

빠른 체크리스트

• Base URL에 /v1이 포함되어 있는지 확인합니다.
• API Key가 매니페스트 외부에 저장되어 있는지 확인합니다.
• Dify, Cursor, Node.js가 동일한 모델 이름을 사용하는지 확인합니다.
• model_not_found가 발생하면 매니페스트를 통해 반증하기 전까지는 라우팅 불일치로 간주합니다.

여러 도구가 하나의 OpenAI 호환 API 중계 스테이션을 공유할 때, 문제는 대개 중계 계층 자체가 아니라 각 도구가 모델 이름, Base URL, API Key 권한을 이해하는 방식이 일치하는지 여부에 있습니다.

이 글에서 벡터 엔진(Vector Engine) API 중계 스테이션과 벡터 엔진 중계 스테이션은 동일한 유형의 접속 계층을 의미합니다. 즉, 여러 모델 라우팅을 검토 가능한 하나의 API 중계 스테이션 설정으로 수렴시키는 계층입니다.

이 튜토리얼은 실용적인 방법을 제시합니다. 코드 저장소에서 소규모 모델 라우팅 목록을 유지 관리하고, 먼저 Node.js로 검증한 다음 동일한 값 세트를 Dify와 Cursor에 복사하는 방식입니다. 벡터 엔진은 LLM API 제공자 계층(LLM API provider layer)에 위치할 수 있지만, 각 클라이언트는 여전히 다음 세 가지 설정이 일치해야 합니다:

• Base URL
• API Key
• 모델 이름 (model name)

라우팅 목록

vector-engine-routes.json 생성:

{
  "provider": "Vector Engine",
  "baseUrl": "https://api.vectorengine.cn/v1",
...

이 파일에는 키를 저장해서는 안 됩니다. API Key는 환경 변수나 키 관리 시스템에 저장하십시오:

export VECTOR_ENGINE_API_KEY="your_key_here"

Node.js 검증 스크립트

check-vector-engine-route.mjs 추가:

import fs from "node:fs/promises";

const manifest = JSON.parse(
...

도구 설정을 수정하기 전에 실행:

node check-vector-engine-route.mjs

스크립트가 model_not_found를 반환하면, 이를 먼저 라우팅 단서로 취급하십시오. API Key는 유효할 수 있으며, 실제로 오류가 있는 부분은 모델 이름, 라우팅 권한 또는 Base URL일 수 있습니다.

동일한 값 세트를 Dify에 복사하기

Dify에서 OpenAI-compatible endpoint 방식으로 제공자를 추가합니다:

• Base URL: https://api.vectorengine.cn/v1
• API Key: Vector Engine에 해당하는 키 사용
• model name: 매니페스트(manifest)에 있는 정확한 model 값 복사

매니페스트를 동시에 업데이트하지 않는 한, Dify에서 모델 필드를 임의로 번역, 축약 또는 수정하지 마세요. 저장소(repository)의 default-chat은 팀 내부용 별칭일 수 있지만, Dify가 실제로 전송하는 것은 제공자(provider) 설정에 있는 모델 문자열입니다.

동일한 값 세트를 Cursor에 복사하기

Cursor의 위험 요소도 이와 유사합니다. Cursor는 사용자 정의 제공자(provider) URL과 키를 수락할 수 있지만, 여전히 벡터 엔진(vector engine)이 라우팅할 수 있는 모델 이름이 필요합니다.

권장 확인 사항:

만약 Cursor에서 model_not_found를 반환한다면, 키를 교체하거나 코드를 수정하기 전에 먼저 가시적인 모델 이름과 매니페스트를 일치시키십시오.

매니페스트가 도움이 되는 이유

공유된 LLM API 제공자 계층(provider layer)은 애플리케이션 팀이 더 빠르게 접속할 수 있게 해주지만, 이는 설정이 가시적으로 유지된다는 전제하에 가능합니다. 이 매니페스트를 통해 코드 리뷰어는 Dify 워크플로우, Cursor 설정 또는 Node.js 서비스가 동일한 벡터 엔진 경로(route)에 접속하기 전에 핵심 파라미터를 빠르게 점검할 수 있습니다.

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

빠른 체크리스트

• Base URL에 /v1이 포함되어 있는지 확인합니다.
• API Key가 매니페스트 파일에 작성되지 않았는지 확인합니다.
• Dify, Cursor, Node.js가 동일한 모델 이름을 사용하는지 확인합니다.
• 매니페스트에서 문제를 해결하기 전까지는 model_not_found를 라우팅 불일치로 간주하여 처리합니다.