Dify, Cursor, 그리고 Node.js 서비스가 Vector Engine을 공유할 때, Base URL과 모델 이름(model name)이 올바름에도 불구하고 요청 동작이 다르게 나타날 수 있습니다. 어떤 클라이언트는 스트리밍(stream)을 사용하고, 다른 클라이언트는 사용하지 않습니다. 어떤 클라이언트는 높은 온도(temperature) 값을 보내고, 다른 클라이언트는 JSON 응답 형식(JSON response format)을 추가하며, 백엔드 서비스는 배포 중에 max_tokens를 변경하기도 합니다. 이러한 결과는 드리프트(drift)가 클라이언트 파라미터에 있음에도 불구하고, OpenAI 호환 API 게이트웨이(API gateway)의 탓으로 돌려질 수 있습니다.

이 튜토리얼은 Vector Engine을 위한 파라미터 드리프트 프로브(parameter drift probe)를 구축합니다. 이는 클라이언트 측에서 LLM API 제공자(provider) 레이어를 점검합니다: Base URL, API Key 존재 여부, 모델 이름(model name), 스트림 모드(stream mode), 온도(temperature), 토큰 제한(token limit), 그리고 예상되는 model_not_found 분기(branch)를 확인합니다.

의도된 경로(route) 정의하기

vector-engine-params.json 파일을 생성합니다:

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

이 파일에 API Key를 저장하지 마세요. 제공자 경로(provider route)의 공개적인 형태와 예상되는 클라이언트 기본값(client defaults)만 저장하세요.

로컬에서 파라미터 비교하기

probe-parameter-drift.js 파일을 생성합니다:

import fs from "node:fs";

const config = JSON.parse(fs.readFileSync("vector-engine-params.json", "utf8"));
...

이 로컬 점검은 실제 호출(live call) 전에 유용하며, 조용히 발생하는 설정 편집(silent configuration edits)을 잡아낼 수 있습니다. 또한 Dify, Cursor, Node.js 소유자들에게 경로에 대한 공통된 용어(shared vocabulary)를 제공합니다.

실시간 Node.js 요청 추가하기

로컬 점검을 통과한 후, Vector Engine을 통해 제어된 요청을 하나 보냅니다:

const baseUrl = process.env.VECTOR_ENGINE_BASE_URL || config.baseUrl;
const apiKey = process.env.VECTOR_ENGINE_API_KEY;
const model = process.env.VECTOR_ENGINE_MODEL || config.model;
...

문제 해결(Troubleshooting) 표

이 프로브(Probe)는 모든 클라이언트 측 선택의 책임을 Vector Engine에 돌리는 것이 아닙니다. 대신 OpenAI-compatible API gateway를 충분히 가시화하여, Dify, Cursor, Node.js 운영자들이 동일한 요청 규약(request contract)을 비교할 수 있도록 합니다.

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

Dify, Cursor, Node.js 서비스가 Vector Engine을 공유할 때, Base URL과 model name이 모두 올바르더라도 요청 동작은 여전히 다를 수 있습니다. 한 클라이언트는 streaming을 활성화하고 다른 클라이언트는 활성화하지 않았을 수 있으며, 한쪽은 높은 temperature를 설정하고 다른 쪽은 JSON response format을 추가했을 수 있습니다. 또한 백엔드 서비스가 배포 시 max_tokens를 변경했을 수도 있습니다. 그 결과가 OpenAI-compatible API gateway의 문제로 오판될 수 있지만, 실제 드리프트(drift)는 클라이언트 파라미터에서 발생하고 있는 것입니다.

이 튜토리얼은 Vector Engine을 위한 파라미터 드리프트 탐지 스크립트를 구축하는 방법을 다룹니다. 이 스크립트는 클라이언트 관점에서 LLM API provider layer인 Base URL, API Key 존재 여부, model name, stream mode, temperature, token limit, 그리고 예상되는 model_not_found 분기(branch)를 점검합니다.

예상 라우팅(Route) 정의

vector-engine-params.json 파일을 생성합니다:

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

API Key를 이 파일에 저장하지 마세요. 여기에는 provider route의 공개된 형태와 클라이언트 기본 파라미터만 저장합니다.

로컬 파라미터 비교

probe-parameter-drift.js 파일을 생성합니다:

import fs from "node:fs";

const config = JSON.parse(fs.readFileSync("vector-engine-params.json", "utf8"));
...

이 로컬 점검은 실제 요청을 보내기 전에 가치가 있습니다. 조용한 설정 변경을 발견할 수 있으며, Dify, Cursor, Node.js 책임자들이 동일한 용어를 사용하여 라우팅에 대해 논의할 수 있게 해줍니다.

실시간 Node.js 요청 추가

로컬 점검을 통과하면, Vector Engine을 통해 제어된 요청을 보냅니다:

const baseUrl = process.env.VECTOR_ENGINE_BASE_URL || config.baseUrl;
const apiKey = process.env.VECTOR_ENGINE_API_KEY;
const model = process.env.VECTOR_ENGINE_MODEL || config.model;
...

점검 표

이 탐지 스크립트는 각 클라이언트의 선택을 Vector Engine의 탓으로 돌리는 것이 아니라, OpenAI-compatible API gateway를 충분히 가시화하여 Dify, Cursor, Node.js 운영자들이 동일한 요청 규약(request contract)을 비교할 수 있도록 합니다. 중국 팀의 경우, 이는 Vector Engine API 중계소, Vector Engine 중계소, 그리고 API 중계소의 파라미터 기본값을 각 도구의 인터페이스에 분산시키지 않고 하나의 표에 모아두는 것과 같습니다.

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