DEV Community

Cover image for DeepSeek Harness에서 모든 모델 실행 방법
Rihpig
Rihpig

Posted on Originally published at apidog.com

DeepSeek Harness에서 모든 모델 실행 방법

DeepSeek Harness(dsh)는 DeepSeek 자체 모델을 내장하지만 특정 모델에 묶이지 않습니다. 제공자를 구성으로 정의하고 OpenAI 호환 엔드포인트와 자격 증명을 연결하면, 로컬 Ollama·사내 게이트웨이·DashScope 호환 모드의 Qwen·Anthropic·OpenAI 등 URL 뒤에 있는 모델을 같은 방식으로 에이전트 세션에서 실행할 수 있습니다.

지금 Apidog 사용해 보기

이 글에서는 제공자 설정 블록의 키를 설명하고, 다음 세 가지 구성 레시피를 제공합니다.

  1. Ollama 로컬 모델
  2. 호스팅된 OpenAI 호환 엔드포인트(DashScope의 Qwen)
  3. 내장 카탈로그 제공자

인용한 구성 내용은 2026년 8월 20일에 확인한 마스터 브랜치의 공식 제공자 가이드를 기준으로 합니다. dsh는 개발자 프리뷰이며, 호환성을 깨뜨리는 변경이 발생할 수 있습니다. 프로덕션에 적용하기 전에 현재 설치한 버전의 문서와 릴리스 노트를 확인하십시오.

DeepSeek Harness가 처음이라면 먼저 DeepSeek Harness의 개념과 동작 방식을 확인한 뒤 이 글의 제공자 설정을 적용하십시오.

에이전트 하네스에서 모델을 교체하는 이유

에이전트 하네스는 다음 루프를 반복합니다.

  1. 모델이 계획을 세웁니다.
  2. 도구를 호출합니다.
  3. 도구 결과를 읽습니다.
  4. 다음 작업을 결정합니다.

하네스는 이 루프를 관리하고, 모델은 교체 가능한 구성 요소입니다. 모델을 교체하는 주요 이유는 세 가지입니다.

비용 관리

에이전트 세션은 도구 결과가 계속 컨텍스트에 추가되므로 토큰 사용량이 빠르게 늘어납니다. 일반 작업은 더 저렴한 모델로 보내고, 복잡한 작업만 더 강력한 모델로 보내면 워크플로를 바꾸지 않고 비용을 조절할 수 있습니다.

예를 들어 일상적인 세션에는 DeepSeek V4-Flash를 사용하고, 고난도 작업에만 V4-Pro를 기본값으로 선택할 수 있습니다.

데이터 지역성

코드베이스나 도구 출력이 외부 네트워크로 나가면 안 되는 환경에서는 자체 인프라의 모델을 가리키면 됩니다. 로컬 런타임 또는 사내 게이트웨이를 baseURL로 설정하면 프롬프트, 파일 내용, 도구 출력이 외부 제공자로 전송되지 않습니다.

로컬 개발과 반복 테스트

플러그인을 개발하거나 에이전트 동작을 검증할 때는 매번 API 크레딧을 소모하거나 네트워크에 의존하지 않는 편이 좋습니다. 작은 로컬 모델로 도구 호출 루프와 플러그인 연결을 먼저 확인한 다음, 실제 작업에서는 더 강력한 모델로 전환할 수 있습니다.

이 구조는 dsh의 플러그인 아키텍처에서 나옵니다. 모델 어댑터도 교체 가능한 플러그인이며, 제공자 경로는 dsh-llm-pi-ai 플러그인이 관리합니다. 자세한 경로 정의는 플러그인 구성 카탈로그에서 확인할 수 있습니다.

사용자 입장에서 필요한 작업은 하나의 YAML 제공자 블록을 추가하는 것입니다.

제공자 블록: 키별 설명

사용자 지정 제공자는 $DSH_HOME/settings.yaml에 추가합니다. 웹 UI에서는 Settings → Models에서 생성할 수 있습니다.

공식 문서의 기본 예시는 다음과 같습니다.

llm-pi-ai:
  providers:
    my-gateway:
      apiKeyEnv: GATEWAY_API_KEY
      api: openai-completions
      baseURL: https://gateway.example/v1
      models:
        - id: legacy-chat
        - id: vision-preview
          input: [text, image]
Enter fullscreen mode Exit fullscreen mode

my-gateway

제공자 ID입니다.

  • 설정에서 이 제공자를 식별하는 영구 이름입니다.
  • 나중에 변경하면 기존 설정이나 참조를 추적하기 어려울 수 있으므로 의미 있는 이름을 사용하십시오.
  • 예: ollama-local, qwen-dashscope, company-gateway

apiKeyEnv

API 키가 들어 있는 환경 변수의 이름입니다.

apiKeyEnv: GATEWAY_API_KEY
Enter fullscreen mode Exit fullscreen mode

실제 키를 YAML에 직접 넣지 마십시오. dsh는 이 이름을 사용해 실행 환경에서 값을 읽습니다.

export GATEWAY_API_KEY="your-secret-key"
Enter fullscreen mode Exit fullscreen mode

api

엔드포인트와 통신할 프로토콜입니다.

api: openai-completions
Enter fullscreen mode Exit fullscreen mode

OpenAI 호환 API를 노출하는 로컬 런타임, 게이트웨이, 호스팅 제공자에는 openai-completions를 사용합니다.

baseURL

dsh가 요청을 보낼 API 루트입니다.

baseURL: https://gateway.example/v1
Enter fullscreen mode Exit fullscreen mode

대부분의 OpenAI 호환 엔드포인트는 /v1까지 포함해야 합니다. DashScope처럼 별도 호환 경로를 사용하는 경우에는 제공자의 문서에 있는 전체 경로를 사용하십시오.

models

이 제공자를 통해 선택할 수 있는 모델 목록입니다.

models:
  - id: legacy-chat
  - id: vision-preview
Enter fullscreen mode Exit fullscreen mode

id는 서버가 요청 본문에서 기대하는 모델 ID와 정확히 일치해야 합니다.

input

모델이 처리할 수 있는 입력 모달리티입니다. 사용자 지정 모델은 기본적으로 텍스트 전용으로 취급됩니다.

비전 모델에는 다음을 명시하십시오.

models:
  - id: vision-preview
    input: [text, image]
Enter fullscreen mode Exit fullscreen mode

제공자의 모든 모델이 이미지를 지원한다면 경로 수준의 defaultInput을 사용할 수 있습니다.

llm-pi-ai:
  providers:
    vision-gateway:
      defaultInput: [text, image]
      # ...
Enter fullscreen mode Exit fullscreen mode

모델별 input은 defaultInput보다 우선합니다.

compat

OpenAI 호환 API이지만 일부 필드 또는 역할을 지원하지 않는 백엔드에 사용하는 호환성 옵션입니다.

문서화된 옵션은 다음과 같습니다.

compat:
  supportsDeveloperRole: false
  maxTokensField: max_tokens
Enter fullscreen mode Exit fullscreen mode
  • supportsDeveloperRole: false: 백엔드가 developer 역할을 거부할 때 사용합니다.
  • maxTokensField: max_tokens: 이전 토큰 제한 필드 이름을 요구할 때 사용합니다.

compat는 제공자 전체 또는 개별 모델에 설정할 수 있습니다.

llm-pi-ai:
  providers:
    legacy-gateway:
      apiKeyEnv: LEGACY_API_KEY
      api: openai-completions
      baseURL: https://legacy.example/v1
      compat:
        supportsDeveloperRole: false
      models:
        - id: legacy-chat
          compat:
            maxTokensField: max_tokens
Enter fullscreen mode Exit fullscreen mode

모델 목록 자동 가져오기

웹 UI에서 사용자 지정 제공자를 추가할 때 Fetch available models를 사용할 수 있습니다. 이 기능은 엔드포인트의 OpenAI 호환 GET /models 경로를 호출해 모델 목록을 채웁니다.

따라서 YAML을 작성하기 전에 먼저 다음 요청이 성공하는지 확인하는 것이 좋습니다.

curl http://localhost:11434/v1/models
Enter fullscreen mode Exit fullscreen mode

API 키는 어디에 저장되는가

비밀 값은 $DSH_HOME/.credentials.yaml에 쓰기 전용으로 저장됩니다.

UI에서 키를 저장하면 dsh는 수정된 설명자만 반환하며, 실제 키 값은 다시 표시하지 않습니다. 반면 settings.yaml에는 다음과 같은 참조만 남습니다.

apiKeyEnv: GATEWAY_API_KEY
Enter fullscreen mode Exit fullscreen mode

이 구조의 장점은 다음과 같습니다.

  • settings.yaml을 공유하거나 커밋할 때 키가 노출되지 않습니다.
  • 제공자 설정을 바꾸지 않고 키만 교체할 수 있습니다.
  • 환경별로 다른 키를 주입할 수 있습니다.

그래도 .credentials.yaml과 환경 변수는 비밀 정보로 취급하고, 저장소에 커밋하지 마십시오.

레시피 1: Ollama로 로컬 모델 실행

Ollama는 http://localhost:11434/v1에서 OpenAI 호환 API를 노출합니다. 자세한 내용은 Ollama의 OpenAI 호환성 가이드에서 확인할 수 있습니다.

다음 설정을 $DSH_HOME/settings.yaml에 추가합니다.

llm-pi-ai:
  providers:
    ollama-local:
      apiKeyEnv: OLLAMA_API_KEY
      api: openai-completions
      baseURL: http://localhost:11434/v1
      models:
        - id: gpt-oss:20b
        - id: qwen3
Enter fullscreen mode Exit fullscreen mode

dsh 공식 제공자 문서에는 Ollama 전용 예시가 없습니다. 이 구성은 dsh의 사용자 지정 제공자 스키마와 Ollama의 문서화된 OpenAI 호환 엔드포인트를 결합한 방식입니다. 적용 전에는 설치 환경에서 반드시 테스트하십시오.

1단계: Ollama 실행 및 모델 준비

먼저 필요한 모델을 내려받습니다.

ollama pull gpt-oss:20b
Enter fullscreen mode Exit fullscreen mode

설치된 모델 목록을 확인합니다.

ollama list
Enter fullscreen mode Exit fullscreen mode

models[].id에는 ollama list에 표시되는 태그를 정확히 입력하십시오. 예를 들어 모델 태그가 gpt-oss:20b라면 YAML도 동일해야 합니다.

2단계: 더미 API 키 환경 변수 설정

Ollama는 로컬 API 키를 요구하지 않지만, dsh 제공자 스키마는 자격 증명 참조를 기대합니다. 따라서 더미 값을 설정합니다.

export OLLAMA_API_KEY=ollama
Enter fullscreen mode Exit fullscreen mode

Ollama는 이 값을 무시합니다.

3단계: dsh에 연결하기 전에 API 확인

먼저 GET /models가 응답하는지 확인하십시오.

curl http://localhost:11434/v1/models
Enter fullscreen mode Exit fullscreen mode

또는 Apidog에서 다음 URL을 호출할 수 있습니다.

http://localhost:11434/v1/models
Enter fullscreen mode Exit fullscreen mode

모델 목록이 반환되면 다음을 확인한 것입니다.

  • Ollama 서버가 실행 중입니다.
  • baseURL이 올바릅니다.
  • dsh UI의 Fetch available models도 사용할 가능성이 높습니다.

로컬 GPT-OSS 실행 절차는 Ollama로 GPT-OSS 실행하기에서 더 자세히 확인할 수 있습니다.

로컬 모델 사용 시 기대치

에이전트 하네스는 도구 호출과 긴 컨텍스트를 많이 사용합니다. 작은 로컬 모델은 다음 용도에는 적합합니다.

  • 플러그인 개발
  • 도구 연결 테스트
  • 프롬프트 흐름 확인
  • 오프라인 반복 작업

다만 최신 대형 모델과 비교하면 계획 능력이 떨어지거나 도구 호출을 놓칠 수 있습니다. 실제 복잡한 작업에서는 더 강력한 모델로 전환하는 것이 적합할 수 있습니다.

레시피 2: 호스팅된 OpenAI 호환 엔드포인트 연결하기

호스팅된 제공자를 연결할 때는 단순히 “OpenAI 호환”이라고 주장하는 서비스보다, 엔드포인트와 인증 방법을 문서화한 제공자를 선택하는 편이 안전합니다.

Alibaba Cloud Model Studio(DashScope)는 Qwen 모델용 OpenAI 호환 엔드포인트를 문서화합니다. DashScope OpenAI 호환성 문서에 따르면 싱가포르 리전의 형식은 다음과 같습니다.

https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1
Enter fullscreen mode Exit fullscreen mode

dsh 설정은 다음과 같습니다.

llm-pi-ai:
  providers:
    qwen-dashscope:
      apiKeyEnv: DASHSCOPE_API_KEY
      api: openai-completions
      baseURL: https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1
      models:
        - id: qwen3-max
Enter fullscreen mode Exit fullscreen mode

적용 절차

  1. {WorkspaceId}를 Model Studio 콘솔의 실제 워크스페이스 도메인으로 바꿉니다.
  2. API 키를 환경 변수에 설정합니다. 
   export DASHSCOPE_API_KEY="your-api-key"
Enter fullscreen mode Exit fullscreen mode
  1. 공급업체의 모델 목록에서 현재 모델 ID를 확인합니다.
  2. 모델 ID를 models[].id에 입력합니다.
  3. 가능하다면 dsh에 추가하기 전에 GET /models로 엔드포인트를 검증합니다.

Qwen 모델 계층은 Qwen 3.8 API 가이드에서도 확인할 수 있습니다.

이 패턴은 OpenAI 호환 API를 문서화한 다른 제공자에도 적용됩니다.

  • Moonshot의 Kimi API
  • OpenRouter
  • vLLM 배포
  • 사내 API 게이트웨이
  • 지역별 모델 제공자

바뀌는 값은 보통 세 가지뿐입니다.

apiKeyEnv: PROVIDER_API_KEY
baseURL: https://provider.example/v1
models:
  - id: provider-model-id
Enter fullscreen mode Exit fullscreen mode

Codex에서 오픈 소스 모델 구성하기를 사용해 본 적이 있다면, dsh의 YAML 블록은 Codex의 model_providers 설정과 유사한 역할을 합니다.

호스팅 엔드포인트에서 자주 필요한 설정

developer 역할 오류

제공자가 다음과 비슷한 오류를 반환할 수 있습니다.

Unsupported role: developer
Enter fullscreen mode Exit fullscreen mode

이 경우 compat를 추가해 보십시오.

compat:
  supportsDeveloperRole: false
Enter fullscreen mode Exit fullscreen mode

토큰 제한 필드 오류

백엔드가 최신 토큰 제한 필드를 지원하지 않는다면 다음 설정이 필요할 수 있습니다.

compat:
  maxTokensField: max_tokens
Enter fullscreen mode Exit fullscreen mode

비전 모델에서 이미지가 무시되는 경우

호스팅 모델이 이미지 입력을 지원하더라도 dsh 설정에서 명시해야 합니다.

models:
  - id: vision-model-id
    input: [text, image]
Enter fullscreen mode Exit fullscreen mode

레시피 3: 내장 카탈로그 제공자 사용

주류 클라우드 모델을 사용한다면 사용자 지정 YAML 블록이 항상 필요한 것은 아닙니다. dsh는 DeepSeek, Anthropic, OpenAI용 카탈로그 제공자를 제공합니다.

일반적인 흐름은 API 키를 추가하고 모델을 선택하는 방식입니다. 일부 카탈로그 제공자는 자체 인증 흐름을 사용합니다.

제공자 유형 인증 또는 설정 방식
Bedrock AWS 자격 증명
Vertex ADC 프로젝트
Azure api-version 필요
Codex OAuth 인증

카탈로그 제공자는 Claude 또는 GPT 같은 주류 모델을 빠르게 연결할 때 마찰이 적습니다. DeepSeek V4-Pro API는 하네스와 함께 2026년 8월에 출시되었으며, 세부 내용은 DeepSeek API 문서에서 확인할 수 있습니다.

반대로 사용자 지정 제공자는 다음과 같은 대상을 연결할 때 사용합니다.

  • 로컬 런타임
  • 사내 게이트웨이
  • 지역별 제공자
  • OpenAI 호환 애그리게이터
  • 카탈로그에 없는 호스팅 모델

모델 선택과 세션 동작

제공자를 추가하면 해당 모델을 선택할 수 있습니다. Settings → Models에서 모델을 선택하면 이후 생성되는 새 세션의 기본값이 됩니다.

다음 두 동작을 이해하고 사용하십시오.

  1. 기존 세션은 시작 시 모델을 유지합니다.

    기본 모델을 변경해도 기존 세션의 모델 기록이나 현재 실행 중인 세션이 자동으로 바뀌지 않습니다.

  2. 기본 모델의 제공자를 삭제하면 새 모델을 선택할 때까지 입력이 차단됩니다.

    dsh는 임의의 대체 모델을 추측하지 않고 명확한 오류를 표시합니다.

이 세션 고정 방식은 재현성에 중요합니다. 예를 들어 DeepSeek Harness와 Claude Code 비교처럼 여러 하네스를 비교할 때, 실행 중간에 모델이 바뀐 것이 아니라 하나의 모델을 기준으로 세션이 진행되었다고 신뢰할 수 있습니다.

일반적인 실패와 해결 방법

baseURL이 잘못되었거나 연결할 수 없음

가장 흔한 문제입니다. URL이 제공자가 기대하는 경로에서 끝나는지 확인하십시오.

  • 일반 OpenAI 호환 API: 보통 /v1
  • DashScope: /compatible-mode/v1

dsh를 실행하기 전에 직접 모델 목록을 요청합니다.

curl \
  -H "Authorization: Bearer $GATEWAY_API_KEY" \
  https://gateway.example/v1/models
Enter fullscreen mode Exit fullscreen mode

Apidog 다운로드 후 같은 요청을 보내면 상태 코드, 응답 헤더, 오류 본문을 빠르게 확인할 수 있습니다. 하네스가 감싼 오류 메시지 대신 실제 API 응답을 보면 원인 파악이 쉬워집니다.

오프라인 개발 중이거나 제공자 API가 불안정하다면 /models와 /chat/completions 응답을 모의(mock)한 뒤, 개발 중에는 baseURL을 모의 서버로 지정할 수 있습니다.

환경 변수가 누락되었거나 비어 있음

apiKeyEnv는 환경 변수의 이름만 지정합니다. 변수를 생성하거나 값을 저장하지는 않습니다.

다음 설정이 있어도:

apiKeyEnv: GATEWAY_API_KEY
Enter fullscreen mode Exit fullscreen mode

실행 환경에 변수가 없다면 요청은 인증 없이 전송되고 401 오류가 발생할 수 있습니다.

echo $GATEWAY_API_KEY
Enter fullscreen mode Exit fullscreen mode

중요한 점은 dsh web을 실행한 동일한 컨텍스트에서 확인해야 한다는 것입니다. GUI, 서비스 관리자 또는 IDE에서 실행한 프로세스는 셸 프로필의 환경 변수를 상속하지 않을 수 있습니다.

이미지 입력이 작동하지 않음

이미지를 첨부했는데 모델이 인식하지 못하거나 API 오류가 발생한다면 모달리티 설정을 확인하십시오.

models:
  - id: vision-model
    input: [text, image]
Enter fullscreen mode Exit fullscreen mode

모든 모델이 비전을 지원한다면 다음처럼 기본값을 설정할 수 있습니다.

llm-pi-ai:
  providers:
    vision-provider:
      defaultInput: [text, image]
Enter fullscreen mode Exit fullscreen mode

역할 또는 토큰 파라미터 오류

지원되지 않는 역할이나 토큰 제한 필드를 언급하는 오류는 compat 설정 대상일 수 있습니다.

compat:
  supportsDeveloperRole: false
  maxTokensField: max_tokens
Enter fullscreen mode Exit fullscreen mode

두 옵션은 문서화된 호환성 스위치입니다. 하나씩 적용하며 제공자 API가 어떤 필드를 거부하는지 확인하십시오.

어제까지 작동하던 설정이 깨짐

dsh는 개발자 프리뷰입니다. 다음 운영 원칙을 적용하십시오.

  1. 배포하는 버전을 고정합니다.
  2. 업그레이드 전에 릴리스 노트를 읽습니다.
  3. 설정 스키마 변경을 예상합니다.
  4. 블로그 글보다 공식 deepseek-harness 리포지토리를 우선합니다.

모델 제공자 구성은 사용자 지정의 절반입니다. 나머지 절반은 에이전트가 호출하는 도구입니다. API 워크플로를 하네스에 연결하려면 DeepSeek Harness에서 Apidog CLI 사용하기를 참고하십시오.

FAQ

DeepSeek Harness는 Ollama를 공식 지원하나요?

공식 제공자 문서에는 Ollama가 명시적으로 언급되어 있지 않습니다. 다만 dsh는 openai-completions 프로토콜을 사용하는 엔드포인트를 지원하며, Ollama는 http://localhost:11434/v1에서 OpenAI 호환 API를 문서화합니다.

이 글의 Ollama 레시피는 문서화된 두 구성을 결합한 것입니다. dsh는 개발자 프리뷰이므로 설치한 버전에서 직접 테스트하십시오.

dsh는 API 키를 어디에 저장하나요?

$DSH_HOME/.credentials.yaml에 쓰기 전용으로 저장합니다.

UI는 저장 후 수정된 설명자만 보여주며, settings.yaml에는 apiKeyEnv 같은 참조만 남습니다. 제공자 설정에 일반 텍스트 키가 포함되지는 않습니다.

세션마다 다른 모델을 사용할 수 있나요?

가능합니다. 모델 선택은 새 세션의 기본값에만 영향을 줍니다. 기존 세션은 시작 당시 사용한 모델을 유지합니다.

예를 들어 일상적인 세션에는 DeepSeek V4-Flash를 사용하고, 어려운 작업을 위해 기본 모델을 더 강력한 모델로 변경해도 기존 세션은 영향을 받지 않습니다.

사용자 지정 엔드포인트가 curl에서는 없던 오류를 반환합니다. 어떻게 해결하나요?

정확한 요청 페이로드를 비교하십시오. 하네스가 백엔드에서 허용하지 않는 developer 역할이나 최신 토큰 제한 필드를 보낼 수 있습니다.

먼저 다음 호환성 설정을 적용해 보십시오.

compat:
  supportsDeveloperRole: false
  maxTokensField: max_tokens
Enter fullscreen mode Exit fullscreen mode

API 클라이언트에서 하네스와 유사한 헤더와 요청 본문을 재현하면, 백엔드가 거부하는 필드를 더 빠르게 찾을 수 있습니다.

Top comments (0)