공유된 Vector Engine 설정은 보통 간단한 구성으로 시작합니다: 하나의 Base URL, 도구당 하나의 API Key, 그리고 Dify, Cursor, Node.js가 모두 사용할 수 있는 모델 이름입니다. 하지만 몇 가지 변경 사항이 발생하면 설정은 더 어려워집니다. 워크플로우 소유자가 Dify를 업데이트하고, 개발자가 Cursor를 변경하며, 서비스 배포 시 Node.js 환경 변수가 변경될 때입니다. model_not_found 에러가 나타나면, 팀은 무엇이 변경되었는지 확인할 수 있는 간결한 방법이 필요합니다.

이 튜토리얼은 OpenAI 호환 API 게이트웨이를 위한 요청 델타(request delta) 보고서를 구축합니다. 이 보고서는 프롬프트나 비밀 정보를 저장하지 않습니다. 대신 LLM API 제공자 계층(provider layer)에서 가장 중요한 제공자 필드들을 비교합니다.

스냅샷 형태 (The snapshot shape)

각 호출자(caller)에 대해 JSON 스냅샷을 생성합니다. 지루할 정도로 예측 가능하게 유지하세요.

{
  "tool": "dify-workflow-a",
  "baseUrl": "configured-openai-compatible-base-url",
...

Dify의 경우, 스냅샷은 제공자 설정(provider settings)과 워크플로우 노트에서 가져옵니다. Cursor의 경우, 커스텀 제공자 설정(custom provider configuration)에서 가져옵니다. Node.js의 경우, 배포 중에 내보낼 수 있습니다.

작은 Node.js 델타 스크립트 (A small Node.js delta script)

스냅샷을 dify.json, cursor.json, node-service.json으로 저장한 다음, 이들을 비교합니다.

import fs from "node:fs";

const files = process.argv.slice(2);
...

실행 방법:

node delta-report.js dify.json cursor.json node-service.json

출력 결과는 의도적으로 단순하게 구성되었습니다. 만약 Dify와 Cursor는 하나의 모델 이름을 사용하지만 Node.js는 다른 이름을 사용한다면, 보고서에 그 내용이 표시됩니다. 모든 도구가 동일한 모델 이름을 사용하더라도 하나의 API Key 범위(scope)가 다르다면, 보고서에 그 내용 역시 표시됩니다.

보고서 활용 방법

보고서를 로그(logs)의 대체제로 만들지 마세요. 대신 타겟팅된 점검을 위한 시작점으로 사용하세요.

차이점(diff) 확인 후 라이브 요청 하나 추가하기

정적 비교를 마친 후, Node.js를 통해 Vector Engine으로 아주 작은 요청 하나를 보냅니다. 이를 통해 선택된 Base URL, API Key, 그리고 모델 이름(model name)이 응답을 생성할 수 있는지 증명할 수 있습니다.

const res = await fetch(`${process.env.BASE_URL}/v1/chat/completions`, {
  method: "POST",
  headers: {
...

만약 코드가 model_not_found를 반환한다면, 다음 담당자는 모델 라우트(model route) 소유자입니다. 만약 Node.js는 성공하지만 Dify가 실패한다면, 다음 담당자는 Dify 프로바이더(provider) 설정 담당자입니다. 만약 Cursor만 단독으로 실패한다면, 다음 담당자는 Cursor 커스텀 프로바이더(custom provider) 엔트리 담당자입니다.

이를 통해 팀은 작은 운영 패턴을 갖게 됩니다: 요청 규약(request contract)을 비교하고, 요청 하나를 재현(replay)한 다음, 변경된 필드에 수정 작업을 할당하는 것입니다.

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

model_not_found 에러가 사용자에게 도달하기 전, Vector Engine을 위한 요청 델타(Request Delta) 보고서 구축하기

공유된 Vector Engine 설정은 보통 간단한 필드에서 시작합니다: 하나의 Base URL, 각 도구별 API Key 하나, 그리고 Dify, Cursor, Node.js에서 모두 사용할 수 있는 모델 이름(model name)입니다. 몇 번의 변경이 지나면 상황은 복잡해집니다. workflow 책임자가 Dify를 업데이트하고, 개발자가 Cursor를 조정하며, 서비스 배포 시 Node.js 환경 변수를 수정하기도 합니다. model_not_found가 발생했을 때, 팀은 정확히 무엇이 바뀌었는지 명확하게 파악할 수 있는 압축된 방식이 필요합니다.

이 튜토리얼은 OpenAI 호환 Vector Engine API 중계소(proxy)에 적합한 요청 차이(request delta) 보고서를 구축하는 방법을 다룹니다. 이 방식은 프롬프트(prompt)나 키(key)를 저장하지 않으며, LLM API 프로바이더 계층(provider layer)에서 가장 중요한 프로바이더(provider) 필드만을 비교합니다.

스냅샷 구조

각 호출자(caller)를 위해 JSON 스냅샷을 생성합니다. 필드는 안정적이어야 하며 복잡해서는 안 됩니다.

{
  "tool": "dify-workflow-a",
  "baseUrl": "configured-openai-compatible-base-url",
...

Dify의 스냅샷은 프로바이더(provider) 설정과 workflow 비고(remark)에서 가져옵니다. Cursor의 스냅샷은 커스텀 프로바이더(custom provider) 설정에서 가져옵니다. Node.js의 스냅샷은 배포 단계에서 내보낼(export) 수 있습니다.

소형 Node.js 차이점 스크립트

스냅샷을 dify.json, cursor.json, node-service.json으로 저장한 다음 비교를 수행합니다.

import fs from "node:fs";

const files = process.argv.slice(2);
...

실행 방법:

node delta-report.js dify.json cursor.json node-service.json

출력은 단순하게 유지됩니다. 만약 Dify와 Cursor는 하나의 모델 이름(model name)을 사용하는데 Node.js는 다른 이름을 사용한다면, 보고서에 표시됩니다. 만약 모든 도구가 동일한 모델 이름(model name)을 사용하지만 그중 하나의 API Key 범위가 다르다면, 이 또한 보고서에 표시됩니다.

보고서 사용법

차이 보고서를 로그(log)의 대체제로 사용하지 마십시오. 이는 특정 문제를 타겟팅하여 조사하기 위한 시작점으로 사용하는 것이 더 적합합니다.

차이점 확인 후 라이브 요청 하나 추가하기

정적 비교를 완료한 후, Node.js를 통해 벡터 엔진 (Vector Engine) 중계소로 작은 요청을 한 번 더 보냅니다. 이를 통해 선택한 Base URL, API Key, 그리고 모델 이름 (model name)이 실제로 응답을 받을 수 있는지 증명할 수 있습니다.

const res = await fetch(`${process.env.BASE_URL}/v1/chat/completions`, {
  method: "POST",
  headers: {
...

만약 코드에서 model_not_found가 반환된다면, 다음 담당자는 모델 라우팅 (model routing) 담당자입니다. 만약 Node.js는 성공하지만 Dify가 실패한다면, 다음 담당자는 Dify 프로바이더 (provider) 설정 담당자입니다. 만약 Cursor만 실패한다면, 다음 담당자는 Cursor 커스텀 프로바이더 (custom provider) 항목 담당자입니다.

이는 하나의 작은 운영 패턴을 형성합니다: 먼저 요청 규약 (request contract)을 비교하고, 요청을 한 번 재현 (replay)한 다음, 변경이 발생한 필드에 수정을 할당하는 방식입니다.

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