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

发布时间2026年8月30日 21:34
栏目guide
语言ko

DeepSeek Harness(dsh) 에이전트 프레임워크 연동 튜토리얼: Web UI 시작, Models 페이지에서 사용자 정의 Provider 추가 및 본 사이트 게이트웨이 지정을 통한 대규모 모델 호출 방법.

1. DeepSeek Harness란 무엇인가

DeepSeek Harness(명령어 dsh)는 DeepSeek에서 오픈 소스로 제공하는 에이전트 프레임워크로, "모든 것이 플러그인(everything-is-a-plugin)" 아키텍처를 채택하고 있습니다. Web UI가 내장되어 있으며, 명령줄 및 SDK 방식으로도 실행할 수 있어 AI가 사용자의 작업 공간에서 파일을 읽고, 코드를 수정하며, 작업을 수행하도록 하는 데 최적화되어 있습니다.

2. Web UI 시작하기

Node.js를 먼저 설치한 후 다음 명령어를 실행하세요:

npx @deepseek-ai/dsh web

이 명령어는 기본적으로 http://127.0.0.1:3080에서 Web 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. 모델을 본 사이트 게이트웨이로 연결하기

Web 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. 일반적인 문제 해결

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

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

Base URL 설명: 본 사이트는 /v1beta/models/...와 /v1beta/v1beta/models/... (및 /v1/...와 /v1/v1/...)를 모두 수용하므로, 클라이언트가 /v1이나 /v1beta를 자동으로 보완하는지 여부와 관계없이 호출할 수 있습니다. Base URL은 도메인 루트 또는 /v1beta가 포함된 주소 모두 사용 가능합니다. 모델 ID는 제어판의 "토큰" 페이지 우측 상단 "모델 ID"에서 확인하고 복사하세요.