DeepSeek Harness 중계 API 연동 튜토리얼: 모델 Provider 설정

DeepSeek Harness(dsh) 에이전트 프레임워크 연동 튜토리얼: 웹 UI 실행, Models 페이지에서 사용자 지정 Provider 추가를 통해 본 사이트 게이트웨이로 대규모 모델을 호출하는 방법 안내.

1. DeepSeek Harness란 무엇인가

DeepSeek Harness(명령어 dsh)는 'everything-is-a-plugin'(모든 것이 플러그인) 아키텍처를 채택한 DeepSeek의 오픈 소스 에이전트 프레임워크입니다. 웹 UI가 내장되어 있으며 명령줄 및 SDK 실행 방식을 지원하여, AI가 워크스페이스 내에서 파일을 읽고, 코드를 수정하며, 작업을 수행하도록 하는 데 적합합니다.

2. 웹 UI 실행하기

먼저 Node.js를 설치한 후 다음 명령어를 실행합니다:

npx @deepseek-ai/dsh web

이 명령어는 기본적으로 http://127.0.0.1:3080에서 웹 UI를 실행하고 자동으로 브라우저를 엽니다. 자동으로 열리는 것을 원치 않으면 --no-open 옵션을 추가하세요. 소스 코드에서 직접 실행하려면 다음과 같이 합니다:

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install && pnpm run build
pnpm dsh web

3. 모델을 본 사이트 게이트웨이로 연결하기

웹 UI → Settings → Models → Add a custom provider를 열고 다음과 같이 입력합니다:

Provider ID : jizhi
Base URL    : https://www.relay-api.com
API 프로토콜 : OpenAI Compatible（openai-completions）
API Key     : sk-당신의 키
모델        : claude-sonnet-5

(OpenAI 엔드포인트는 https://www.relay-api.com/v1을, Gemini 엔드포인트는 https://www.relay-api.com/v1beta를 사용하며, 필요에 따라 여러 Provider를 추가할 수 있습니다.)

settings.yaml 파일에서도 설정 가능합니다

llm-pi-ai:
  providers:
    jizhi:
      apiKeyEnv: JIZHI_API_KEY
      api: openai-completions
      baseURL: "https://www.relay-api.com"
      models:
        - id: claude-sonnet-5

저장 후 모델 선택기에서 해당 모델을 선택하면 대화를 시작할 수 있습니다.

4. 워크스페이스 선택 및 작업 실행

실행 후 Choose workspace를 클릭하여 dsh를 시작한 프로젝트 디렉토리를 선택하세요. 워크스페이스를 선택하면 새 세션을 만들 수 있습니다. 예를 들어 "이 저장소를 요약하고 주요 패키지를 나열해 줘"라고 요청해 보세요. 프레임워크는 권한이 필요한 경우 사용자에게 동의를 구합니다.

5. 자주 묻는 질문(FAQ)

현상	조치
401	키가 유효하지 않음; API Key를 확인하거나 Models 페이지에서 다시 입력하고, 해당 환경 변수를 노출하세요.
UNKNOWN_MODEL	모델이 설정되지 않았거나 일치하지 않음; 사용자 지정 Provider의 모델 목록에 정확한 슬러그(slug)를 추가하세요.
게이트웨이 거부	요청 구조가 OpenAI와 완전히 일치하지 않는 경우, route 설정에서 `compat.supportsDeveloperRole: false` 및 `compat.maxTokensField: max_tokens`를 구성해 보세요.

보안 권장 사항: sk- 키를 공개 저장소에 작성하지 말고, 환경 변수를 통해 참조하는 것을 권장합니다. 에이전트 작업량이 많을 수 있으니 잔액과 사용량을 주의 깊게 확인하세요.