팀이 Dify, Cursor, 그리고 Node.js 서비스를 Vector Engine에 연결할 때, 겉으로 보이는 설정은 대개 간단합니다. 하나의 OpenAI 호환 API 게이트웨이(API gateway), 하나의 Base URL, 하나의 API Key 정책, 그리고 경로당 하나의 모델 이름(model name)만 있으면 됩니다. 숨겨진 문제는 오래된 직접 제공자(direct-provider) URL이 환경 파일(environment files), 워크플로우 변수(workflow variables), CI 비밀값(CI secrets), 또는 개발자 머신에 남아 있을 수 있다는 점입니다.

이 튜토리얼은 작은 규모의 egress host 감사(egress host audit)를 구축합니다. 이 감사는 모델을 호출하지 않습니다. 트래픽이 애플리케이션 경계를 벗어나기 전에 설정을 확인하므로, 팀은 모든 도구가 직접 제공자와 공유 게이트웨이를 혼용하는 대신 LLM API 제공자 계층으로서 Vector Engine을 사용하고 있는지 확인할 수 있습니다.

감사가 포착해야 할 사항

감사는 워크플로우를 프로덕션(production)으로 옮기기 전에 유용합니다:

핵심은 실험을 차단하는 것이 아닙니다. 프로덕션 경로를 명확하게 만드는 것이 목적입니다.

설정 파일 예시

감사를 위해 로컬 파일 하나를 유지하세요. 리포지토리(repository)에는 플레이스홀더(placeholders)를 사용하고, 배포 시스템(deployment system)에는 실제 값을 사용하세요.

{
  "approvedHost": "api.vectorengine.cn",
  "tools": [
...

API Key 값은 이 파일에 저장되지 않는다는 점에 유의하세요. 감사는 예상되는 변수가 런타임 환경(runtime environment)에 존재하는지 여부만 확인합니다.

Node.js 감사 스크립트

이 내용을 audit-vector-engine-egress.mjs로 저장하세요.

import fs from "node:fs";

const configPath = process.argv[2] || "vector-engine-egress.json";
...

애플리케이션에서 사용하는 것과 동일한 비밀값(secret) 이름을 사용하여 CI에서 실행하세요:

node audit-vector-engine-egress.mjs vector-engine-egress.json

만약 Base URL이 여전히 직접 제공업체(direct provider)를 가리키고 있어 스크립트가 실패한다면, Dify나 Cursor를 테스트하기 전에 설정을 수정하십시오. 만약 API Key 변수가 누락되어 실패한다면, Secret 주입(secret injection)을 수정하십시오. 만약 모델 이름(model name)이 여전히 플레이스홀더(placeholder)여서 실패한다면, 이후의 model_not_found 오류를 게이트웨이 문제로 간주하기 전에 라우트 레코드(route record)를 업데이트하십시오.

이것이 model_not_found 해결에 도움이 되는 방법

model_not_found는 요청이 실제로 예상된 제공업체 경로에 도달했을 때만 유용합니다. 만약 Dify는 Vector Engine을 가리키고 있지만 Cursor는 다른 호스트를 가리키고 있다면, 동일한 모델 이름이라도 서로 다른 실패를 발생시킬 수 있습니다. 만약 Node.js가 오래된 Secret을 사용한다면, 팀은 인증 오류(authorization error)를 보고 모델 라우트를 변경하는 데 시간을 허비할 수 있습니다.

Egress 감사(audit)는 그러한 모호함을 줄여줍니다. 이는 런타임 디버깅(runtime debugging)을 수행하기 전에 팀에게 다음과 같은 짧은 답변을 제공합니다:

1. 모든 도구가 동일한 Base URL 호스트를 사용하고 있는가?
2. 각 도구가 API Key 변수를 가지고 있는가?
3. 각 도구가 동일한 모델 이름 정책(model name policy)을 선언하고 있는가?
4. 각 항목에 소유자(owner)가 지정되어 있는가?
5. 어떤 도구가 OpenAI 호환 API 게이트웨이를 우회하고 있는가?

출력 결과는 애플리케이션 로그가 아닌 빌드 로그(build logs)에 유지하십시오. 로그에는 호스트, 변수 이름, 모델 이름, 소유자가 표시되어야 하지만, 절대로 Secret 값은 포함되어서는 안 됩니다.

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

Dify, Cursor, Node.js가 Vector Engine을 공유하기 전 Egress Host 감사(Audit) 수행하기

팀이 Dify, Cursor, Node.js 서비스를 벡터 엔진(Vector Engine)에 연결할 때, 표면적인 설정은 대개 매우 간단합니다. 하나의 OpenAI 호환 API 게이트웨이, 하나의 Base URL, 하나의 API Key 관리 방식, 그리고 각 라우트(route)에 대응하는 모델 이름(model name)이 그것입니다. 숨겨진 문제는 기존의 직접 연결된 제공업체(direct provider) URL이 환경 변수, 워크플로우 설정, CI Secret 또는 개발자의 로컬 머신에 여전히 남아 있을 수 있다는 점입니다.

이 튜토리얼은 소규모 Egress Host 감사를 수행합니다. 이 감사는 모델을 호출하지 않으며, 트래픽이 애플리케이션 경계를 벗어나기 전에 설정을 점검하여, 모든 도구가 직접 연결된 제공업체와 공유 API 중계소를 혼용하는 대신 벡터 엔진을 LLM API 제공업체 계층(provider layer)으로 사용하고 있는지 팀이 확인할 수 있도록 돕습니다.

이 감사를 통해 무엇을 발견해야 하는가

배포 전에 다음 내용들을 점검할 수 있습니다:

이것은 실험을 제한하기 위함이 아니라, 프로덕션 경로(production path)를 가시화하기 위함입니다.

예시 설정 파일

영어 부분에서는 JSON 예시를 제공했습니다. 핵심 요점은 다음과 같습니다: Base URL은 https://api.vectorengine.cn/v1을 가리키며, 도구에는 Dify, Cursor, Node.js가 포함됩니다. 각 도구는 API Key 환경 변수, 모델 이름(model name), 그리고 소유자(owner)를 선언합니다.

API Key 값을 파일에 직접 작성하지 마세요. 감사(Audit)는 실행 환경(runtime environment)에 예상되는 변수가 존재하는지만 확인합니다.

Node.js 스크립트 로직

스크립트는 설정을 읽어 각 Base URL의 호스트(host)를 파싱하고, 이를 승인된 호스트와 비교합니다. 만약 이전 프로바이더(provider)의 호스트, 누락된 API Key 변수, 자리 표시자(placeholder) 모델 이름(model name), 또는 누락된 소유자(owner)가 발견되면 해당 도구를 실패(fail)로 표시합니다.

실행 방법은 매우 간단합니다:

node audit-vector-engine-egress.mjs vector-engine-egress.json

만약 실패 원인이 Base URL이 여전히 프로바이더로 직접 연결(direct connection)을 가리키고 있기 때문이라면, 설정을 먼저 수정한 후 Dify 또는 Cursor를 테스트하세요. 실패 원인이 API Key 변수 누락이라면 Secret 주입(injection)을 수정하세요. 만약 실패 원인이 모델 이름이 여전히 자리 표시자이기 때문이라면, 모델 라우팅(model routing) 기록을 먼저 보완해야 합니다. 이후 발생하는 model_not_found 오류를 벡터 엔진 중계소(vector engine relay)의 직접적인 원인으로 돌리지 마세요.

model_not_found 문제 해결에 어떻게 도움이 되는가

요청이 실제로 예상된 프로바이더 경로(provider path)로 진입할 때만 model_not_found 오류를 조사할 가치가 있습니다. 만약 Dify는 벡터 엔진 API 중계소를 가리키고 있는데 Cursor는 다른 호스트를 가리키고 있다면, 동일한 모델 이름(model name)이라도 완전히 다른 오류가 발생할 수 있습니다. 만약 Node.js가 만료된 Secret을 사용한다면, 팀은 인증 실패(authentication failure)를 보고하면서도 이를 모델 라우팅 문제로 오해할 수 있습니다.

Egress 감사(Egress audit)는 런타임(runtime) 오류를 디버깅하기 전에 몇 가지 질문에 답해줄 수 있습니다:

1. 모든 도구가 동일한 Base URL 호스트를 사용하는가?
2. 각 도구에 API Key 변수가 있는가?
3. 각 도구가 동일한 모델 이름(model name) 전략을 선언했는가?
4. 각 설정에 소유자(owner)가 지정되어 있는가?
5. OpenAI 호환 API 게이트웨이(API gateway)를 우회하는 도구가 있는가?

출력 결과는 빌드 로그(build log)에 남겨두기만 하면 됩니다. 출력에는 호스트(host), 변수명, 모델 이름(model name), 소유자(owner)가 표시되어야 하지만, 어떠한 Key 값도 출력해서는 안 됩니다. 이렇게 하면 벡터 엔진 중계소의 접속 경로가 더 명확해지며, API 중계소의 디버깅 과정에서 오판을 훨씬 줄일 수 있습니다.

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