요약: DeepSeek Harness는 “사용자 정의 모델 API”를 통해 APIYI 같은 게이트웨이에 연결할 수 있어요. 개발자는 프로토콜별로 제공자를 따로 설정하고, 게이트웨이가 실제로 지원하는 모델 ID를 입력하며, 작업 요구에 따라 웹 검색 도구를 별도로 연결하면 돼요.
DeepSeek Harness는 서드파티 API 게이트웨이를 사용자 정의 모델 제공자로 추가할 수 있으며, OpenAI Chat Completions, OpenAI Responses, Anthropic Messages, Gemini API 네 가지 프로토콜 중에서 선택할 수 있어요. 따라서 하나의 Harness 인스턴스가 APIYI(apiyi.com) 같은 통합 게이트웨이를 통해 여러 벤더의 모델을 동시에 호출할 수 있죠. 연결 성공 여부는 네 가지에 달려 있어요. 프로토콜과 Base URL의 일치, 모델 ID와 게이트웨이의 일치, 추론 및 출력 파라미터의 호환성, 그리고 웹 검색 도구를 별도로 계획했는지 여부예요.
아래에서는 먼저 Harness의 모델 어댑팅 메커니즘과 그 안에서 게이트웨이가 어떤 위치를 차지하는지 설명한 뒤, 설정 화면을 따라 사용자 정의 제공자 구성을 항목별로 완료하고, APIYI용 구성 파일 템플릿을 제시할게요. 이어서 인터페이스는 연결되지만 호출이 실패할 때 가장 흔한 호환성 문제와 오류 코드를 정리하고, DeepSeek 서버 내장 검색과 APIYI의 독립 Search / Fetch라는 두 가지 웹 검색 경로를 구분한 다음, 마지막으로 멀티 모델 Agent의 계층형 설계와 배포 제안을 드릴게요.

알아두기: DeepSeek Harness 다중 모델 연동 용어
| 용어 | 설명 |
|---|---|
| Harness | Agent의 실행 프레임워크로, 모델 연동, 도구 호출, 컨텍스트, 세션 및 작업 실행 루프를 담당합니다 |
| API Gateway | 여러 모델의 API 요청을 통합 전달·관리하는 게이트웨이로, 외부에는 하나의 진입점만 노출합니다 |
| Base URL | API 요청의 기본 주소로, 프로토콜이 다르면 주소의 경로 접두사도 달라집니다 |
| Provider | Harness에 구성된 하나의 모델 서비스 제공자로, 하나의 주소·프로토콜·키 조합에 대응합니다 |
| Model ID | 요청에서 지정하는 모델 식별자로, 게이트웨이가 실제로 제공하는 이름과 반드시 일치해야 합니다 |
| Chat Completions | OpenAI 스타일의 대화 완성 인터페이스로, 게이트웨이에서 가장 흔히 호환되는 프로토콜입니다 |
| Responses API | OpenAI의 구조화된 응답 인터페이스로, 도구 호출과 다중 턴 상호작용을 겨냥합니다 |
| Anthropic Messages | Anthropic 스타일의 메시지 인터페이스로, Claude 시리즈 모델의 네이티브 프로토콜입니다 |
| Reasoning Effort | 모델의 사고 수준 파라미터로, off, low, medium, high, max 등이 있습니다 |
| Tool Calling | 모델이나 Agent가 외부 도구를 호출하기로 결정하고, 그 결과를 이후 추론에 활용하는 것을 말합니다 |
| Search / Fetch | Search는 웹 검색을 수행해 결과 목록을 반환하고, Fetch는 지정한 웹페이지의 본문을 가져옵니다 |
| API Key | 신원 인증 자격 증명으로, 요청이 어떤 모델과 인터페이스에 접근할 수 있는지를 결정합니다 |
1 DeepSeek Harness가 멀티모델 API 연동에 적합한 이유
1.1 DeepSeek Harness의 모델 프로바이더 메커니즘
DeepSeek Harness는 2026년 8월 13일 개발자 프리뷰 버전으로 오픈소스 공개됐고, MIT 라이선스를 채택했어요. 핵심 아키텍처는 ‘Everything is a Plugin’이에요. 모델 어댑터, 도구, Skills, 스토리지, 세션 관리는 모두 교체 가능한 플러그인이라서, 모델 연동은 제품에 고정된 벤더 종속이 아니라 열린 구성 항목이 돼요.
모델 계층에서 Harness는 사용자가 여러 프로바이더를 추가하고 세션 중에 모델을 전환할 수 있게 해요. 각 프로바이더에는 API 키, Base URL, 모델 이름, API 프로토콜, 컨텍스트 길이, 최대 출력 토큰, 이미지 입력 지원 여부, 추론 수준을 설정할 수 있어요. API 중계 서비스, 사내 게이트웨이, 자체 구축 모델 서비스 모두 독립적인 프로바이더로 연결할 수 있어요.
다만 Harness는 아직 개발자 프리뷰 단계라, 공식 측에서 향후 버전에 호환성을 깨는 변경이 있을 수 있다고 안내하고 있어요. 프로덕션 환경에서 쓰기 전에는 버전을 고정하고 구성을 백업하는 걸 권장해요.
1.2 API 게이트웨이가 DeepSeek Harness에서 하는 역할
Harness 입장에서 게이트웨이는 곧 하나의 프로바이더예요. 네 개의 필드가 한 번의 요청 경로를 결정해요. Base URL은 게이트웨이 주소를 가리키고, 프로토콜은 요청과 응답의 형식을 정해요. API 키는 호출자의 신원을 증명하고, Model ID는 게이트웨이가 요청을 어느 모델로 전달해야 하는지 알려줘요.
APIYI(apiyi.com)를 예로 들면, 플랫폼은 하나의 API 키로 OpenAI, Claude, Gemini, DeepSeek 등의 모델을 제공하고, OpenAI 호환, Anthropic 네이티브, Gemini 세 가지 프로토콜 진입점을 열어둬요. Harness에서는 프로토콜에 맞춰 해당 프로바이더만 만들면 되고, 모델 전환은 Model ID를 바꾸는 일이 돼요. 벤더마다 별도 계정을 신청하고 키를 관리할 필요가 없어요.

2 DeepSeek Harness에서 사용자 정의 모델 제공자 제로부터 구성하기
2.1 DeepSeek Harness 모델 구성 인터페이스 열기
로컬에서 Harness를 가장 빠르게 시작하는 방법은 공식 npm 명령어예요. Node.js를 미리 설치해야 해요:
npx @deepseek-ai/dsh web
# 기본적으로 로컬 Web UI가 열립니다: http://127.0.0.1:3080
인터페이스에 진입한 후 설정 → 모델 → 모델 제공자 추가 → 사용자 정의 모델 API를 차례로 클릭하면 제공자 구성 폼을 볼 수 있어요. 공식 데스크톱 버전은 macOS Apple Silicon과 Windows 64비트 설치 패키지를 제공하며, 구성 경로는 동일해요.
2.2 DeepSeek Harness 제공자 정보 입력
| 설정 항목 | 역할 | 입력 요령 |
|---|---|---|
| Provider ID | 제공자 고유 식별자 | 반드시 소문자로 입력해야 하며, 생성 후에는 이름을 바꿀 수 없어요. 예: apiyi |
| 표시 이름 | 모델 메뉴에 표시되는 이름 | “APIYI OpenAI 호환”처럼 작성할 수 있어요 |
| API 프로토콜 | 요청과 응답의 형식 | Base URL과 일치해야 하며, 2.3을 참고하세요 |
| Base URL | API 서비스 주소 | 버전 접두사에 주의하세요. 2.4를 참고하세요 |
| API 키 | 인증 자격 증명 | 자격 증명 파일에 저장되며, 화면에는 마스킹된 미리보기만 표시돼요 |
| Model ID | 실제 호출하는 모델 이름 | 게이트웨이 모델 목록과 완전히 일치해야 해요 |
| Context Window / Max Output Tokens | 컨텍스트 및 최대 출력 길이 | 모델의 실제 사양에 맞게 입력하세요 |
| Input Type | 텍스트 또는 이미지 입력 | 비전 모델에만 이미지 항목을 체크하세요 |
| Reasoning Effort | 사고 수준과 파라미터 매핑 | 모델이 실제로 지원하는 단계만 추가하세요 |
Provider ID는 이름을 바꿀 수 없는데, 그 이유는 모델 구성, 과거 대화 기록, 자격 증명 참조가 모두 이 ID를 가리키기 때문이에요. 교체가 필요할 때는 새 제공자를 먼저 만들고, 그다음에 기존 제공자를 삭제하면 돼요.
폼의 “사용 가능한 모델 가져오기” 버튼은 게이트웨이에서 모델 목록을 읽어오려고 시도해요. 게이트웨이가 표준 모델 목록을 제공하지 않거나, 반환 형식이 Harness가 인식할 수 있는 범위를 벗어난다면 Model ID를 직접 추가하면 돼요. 결과는 동일해요.
2.3 DeepSeek Harness의 API 프로토콜 선택
Harness 커스텀 모델 API는 OpenAI Chat Completions, OpenAI Responses, Anthropic Messages, Gemini API 네 가지 프로토콜을 지원해요. 하나의 제공자는 하나의 프로토콜에만 바인딩될 수 있어요. 같은 게이트웨이가 세 가지 프로토콜 엔트리를 열어둔다면, 제공자를 세 개 만들어야 하죠.
프로토콜 선택은 모델 패밀리를 따라가요. GPT, DeepSeek 그리고 대부분의 중국산 모델은 OpenAI Chat Completions를 쓰는 게 가장 안정적이에요. Claude 시리즈는 네이티브 기능을 유지하고 싶다면 Anthropic Messages를 선택할 수 있고, Gemini 시리즈는 Gemini API를 사용해요. Responses 프로토콜은 구조화된 응답과 도구 호출이 필요한 시나리오에 적합한데, 게이트웨이와 대상 모델 모두 해당 인터페이스를 지원해야 한다는 전제가 있어요.
2.4 APIYI로 DeepSeek Harness 인스턴스 구성하기
APIYI에서 공식적으로 안내하는 프로토콜과 Base URL 대응 관계는 다음과 같아요:
| 프로토콜 | APIYI Base URL | 적용 모델 | 사용 가능 플랫폼 |
|---|---|---|---|
| OpenAI 호환(Chat Completions) | https://api.apiyi.com/v1 |
GPT, DeepSeek 등 | APIYI apiyi.com, 각 벤더 공식 API |
| Anthropic 네이티브 | https://api.apiyi.com |
Claude 시리즈 | APIYI, Anthropic 공식 |
| Gemini | https://api.apiyi.com/v1beta |
Gemini 시리즈 | APIYI, Google 공식 |
Anthropic 프로토콜은 루트 도메인을 사용하고, 어댑터가 이후 경로를 자체적으로 이어 붙여요. 루트 도메인 뒤에 /v1을 추가로 적으면 경로가 중복되면서 404가 반환될 수 있어요. Responses 프로토콜 연동 방식은 APIYI Responses API 문서를 참고해 확인한 뒤 입력하는 걸 권해요.
인터페이스 설정 외에도 Harness는 구성 파일 직접 편집을 지원하는데, 위치는 $DSH_HOME/profiles/web/cordis.patch.yml이에요. 아래는 공식 구성 구조에 맞춰 작성한 APIYI OpenAI 호환 제공자 템플릿이에요:
- id: llm-pi-ai
config:
providers:
apiyi:
apiKeyEnv: APIYI_API_KEY # 환경 변수에서 키 읽기
api: openai-completions # OpenAI Chat Completions 프로토콜
baseURL: https://api.apiyi.com/v1 # APIYI OpenAI 호환 엔트리
models:
- id: MODEL_ID_FROM_APIYI # 계정에서 실제 사용 가능한 모델 ID로 교체
사용 순서는 이렇게 돼요:
- 환경 변수
APIYI_API_KEY를 설정해요. MODEL_ID_FROM_APIYI를 APIYI 콘솔에서 실제로 호출 가능한 모델 이름으로 바꿔요.- 설정을 저장하고 Harness 모델 선택기에서
apiyi제공자와 해당 모델을 선택해요. - 간단한 대화를 한 번 보내 인터페이스가 정상 동작하는지 확인해요.
이 템플릿은 공식 구성 구조를 보여주는 예시이고, 모델 이름은 자신의 계정에서 호출 가능한 목록을 기준으로 하면 돼요. 모델 구성 변경은 보통 다음 요청 시점에 적용되며, Web UI를 재시작할 필요는 없어요. 인터페이스 설정은 일상적인 모델 추가와 키 수정에 적합하고, 구성 파일은 호환 파라미터, 추론 모드, 타임아웃, 재시도 같은 고급 설정 조정에 적합해요.
Harness에 연결하기 전에는 스크립트로 Key와 Model ID를 먼저 단독 검증하는 걸 추천해요. “게이트웨이 사용 가능”과 “Harness 구성 정확”이라는 두 문제를 분리해서 점검하는 거죠:
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["APIYI_API_KEY"],
base_url="https://api.apiyi.com/v1" # APIYI apiyi.com OpenAI 호환 엔트리
)
resp = client.chat.completions.create(
model="MODEL_ID_FROM_APIYI", # Harness에 입력한 Model ID와 동일하게 유지
messages=[{"role": "user", "content": "用一句话介绍你自己"}],
max_tokens=100
)
print(resp.choices[0].message.content)
🚀 빠른 시작 팁: 신규 사용자는 APIYI apiyi.com에서 가입한 뒤 무료 테스트 크레딧을 받아, 위 스크립트로 모델 ID가 사용 가능한지 먼저 확인하고 Harness 구성에 입력하면 전체적인 트러블슈팅 시간이 훨씬 짧아져요.
3 DeepSeek Harness 인터페이스는 연결되는데도 모델 호출이 실패하는 이유
Harness 공식 문서에 따르면, API 주소와 키가 모두 올바르더라도 게이트웨이가 여전히 요청을 거부할 수 있어요. 원인은 호환 인터페이스마다 메시지 역할, 출력 길이, 사고 파라미터에 대한 요구 사항이 다르기 때문이에요. 아래 세 가지 compat 파라미터가 이런 문제를 해결해 주며, 인터페이스가 실제로 반환하는 오류에 따라 필요한 것만 켜면 됩니다.
3.1 Developer 역할 호환
최신 OpenAI 규격은 role: developer를 도입했지만, 일부 호환 게이트웨이는 system만 인식해요. “모든 요청이 실패”하거나 “추론 모델만 실패”하는 상황이 나오면 developer 역할을 꺼 주세요:
compat:
supportsDeveloperRole: false
이 옵션을 켜면 어댑터가 요청 안의 역할 처리 방식을 조정해서, 게이트웨이가 받아들일 수 있는 형식으로 맞춰 줘요.
3.2 최대 출력 파라미터 호환
OpenAI 신규 인터페이스는 최대 출력을 max_completion_tokens로 표시하지만, 일부 게이트웨이는 전통적인 max_tokens만 받아요. 의미는 같은데 필드명이 다르면 파라미터 검증 실패로 이어집니다. 설정은 이렇게 해요:
compat:
maxTokensField: max_tokens
3.3 DeepSeek 사고 모드 호환
일부 DeepSeek 모델은 사고(thinking) 기능이 기본으로 켜져 있어요. Harness에서 추론 레벨을 off로 설정하면 일부 호환 프로토콜은 추론 파라미터만 생략하는데, 그러면 모델이 기본 동작대로 계속 사고해서 “off로 못 끈다”는 현상이 생겨요. 이를 위해 공식에서 DeepSeek 전용 사고 형식을 제공합니다:
compat:
thinkingFormat: deepseek
이 옵션을 켜면 사고를 끌 때 어댑터가 명시적으로 {"thinking": {"type": "disabled"}}를 보내고, 켤 때는 {"thinking": {"type": "enabled"}}를 보냅니다. 공식 예시는 OpenAI 호환 게이트웨이 뒤에 있는 DeepSeek V4 모델을 대상으로 해요. 멀티모델 게이트웨이에서는 DeepSeek 모델에만 이 파라미터를 따로 설정하고, GPT·Claude 같은 모델은 기본값을 유지하면 됩니다.
추론 레벨 쪽에서는 Harness가 UI의 off, low, medium, high, max를 API가 실제로 받아들이는 파라미터 값으로 매핑할 수 있어요. 모델이 진짜 지원하는 등급만 설정에 넣어 두면, 사용자가 무효한 등급을 선택한 뒤 요청이 오류를 내는 일을 피할 수 있습니다. 세 가지 호환 파라미터를 합친 전체 예시는 다음과 같아요:
- id: llm-pi-ai
config:
providers:
apiyi:
apiKeyEnv: APIYI_API_KEY
api: openai-completions
baseURL: https://api.apiyi.com/v1
compat:
supportsDeveloperRole: false
maxTokensField: max_tokens
models:
- id: MODEL_ID_FROM_APIYI
3.4 DeepSeek Harness 흔한 오류 빠른 점검
| 오류 또는 증상 | 가능한 원인 | 처리 방법 |
|---|---|---|
| MISSING_CREDENTIAL | 키가 설정되지 않음 | API Key와 환경 변수 이름 확인 |
| UNKNOWN_MODEL | 모델 ID가 등록되지 않음 | 제공업체 아래에 올바른 모델 ID 추가 |
| HTTP 401 | 키가 유효하지 않거나 권한 부족 | 키 내용과 소속 그룹 확인 |
| HTTP 404 | Base URL 경로 오류 | 프로토콜과 버전 접두사(/v1, 루트 도메인, /v1beta) 확인 |
| 모델 목록이 비어 있음 | 게이트웨이가 표준 모델 목록 인터페이스를 지원하지 않음 | 모델 ID 수동 추가 |
| 모든 요청이 실패 | 역할 또는 파라미터 형식 충돌 | compat 호환 파라미터 확인 |
| 추론 모델만 실패 | Developer 역할 비호환 | supportsDeveloperRole: false 설정 |
| off로 사고를 끌 수 없음 | 모델이 기본적으로 사고를 켜 둠 | thinkingFormat: deepseek 설정 |
| 검색 인터페이스가 503 반환 | 토큰 그룹에 도구 권한이 없음 | default 또는 svip 그룹 토큰으로 변경 |
| 대화는 정상, 웹 검색만 안 됨 | 검색 도구가 미통합이거나 프로토콜 미지원 | 도구 기능과 클라이언트 설정 확인 |
앞의 여덟 항목은 Harness 공식 설정 문서를 근거로 했고, 그룹 관련 문제는 APIYI 공식 문서에서 가져왔어요. 점검 순서는 위에서 아래로 진행하는 걸 권장합니다. 먼저 자격 증명을 확인하고, 다음으로 모델 ID, 그다음이 경로, 마지막이 파라미터 호환이에요.
4 DeepSeek Harness에 웹 검색 기능 추가하기
4.1 모델 내장 검색과 독립 검색 API 구분하기
일반 대화 호출이 성공했다고 해서 증명되는 건 API 키가 유효하고, 모델 ID가 정확하며, 대화 프로토콜이 기본적으로 호환된다는 정도뿐이에요. 웹 검색 능력은 모델이 해당 도구를 지원하고, 요청에서 도구를 올바르게 선언하고, API 서비스가 그 도구 프로토콜을 지원하며, Harness가 도구 응답을 처리할 수 있어야 하고, 또는 개발자가 애플리케이션 측에서 검색을 별도로 통합해야 해요. 그러므로 대화 성공과 웹 검색 성공은 서로 독립적인 두 개의 검증 단계예요.
DeepSeek 생태계에서 웹 검색 능력을 구현하는 방법에는 두 가지 기술 경로가 있어요:

| 구분 | 경로 A: 모델 내장 서버 측 도구 | 경로 B: 독립 Search / Fetch API |
|---|---|---|
| 호출 방식 | 대화 요청에서 deepseek_web_search, deepseek_read_url 선언 |
프로그램이 /v1/tools/search, /v1/tools/fetch를 직접 요청 |
| 검색 결정 주체 | 모델이 자율 판단 | 개발자 또는 Agent 도구 로직 |
| 도구 실행 | DeepSeek 서버에서 검색과 컨텍스트 결합까지 처리 | 클라이언트가 결과를 받은 뒤 자체 처리 |
| 모델 범위 | 공식 공지에서 명확히 deepseek-flash를 대상으로 명시 |
모델과 무관하며 어떤 모델이든 결과를 재사용 가능 |
| 과금 기준 | 실제 검색어 개수, 크롤링한 웹 페이지 수 등을 기준으로 과금 | 성공한 요청 횟수를 기준으로 과금, 모델 Token 소모 없음 |
| 현재 사용 가능한 채널 | DeepSeek 공식 API | DeepSeek 공식 API, APIYI |
4.2 모델 내장 검색의 작동 방식
2026년 11월 13일, DeepSeek은 App 뒤에 있는 여러 애플리케이션 기능을 개방했어요. 그중 웹 검색과 링크 읽기는 서버 측 도구 형태로 제공해요. 요청의 도구 목록에 선언하기만 하면 돼요:
[
{"type": "deepseek_web_search", "name": "deepseek_web_search"},
{"type": "deepseek_read_url", "name": "deepseek_read_url"}
]
선언하면 모델이 스스로 웹 연결이 필요한지 판단하고 검색어를 생성하며, DeepSeek 서버 측에서 검색을 실행한 뒤 출처 인용이 포함된 답변을 반환해요. 사고 모드를 켜면 검색이 다단계 프로세스로 업그레이드되어, 모델이 여러 키워드를 검색하고, 웹페이지를 열고, 페이지 내에서 검색하며 교차 검증할 수 있어요. 공식 문서에 따르면 최대 약 20회의 도구 호출 후 답변을 작성한다고 해요. deepseek_read_url은 마지막 사용자 메시지에 있는 URL만 인식하며, 최대 10개의 서로 다른 링크를 고려해요.
개발자는 여전히 반환되는 콘텐츠 블록, 인용 정보, 스트리밍 이벤트, 다중 턴 기록을 처리해야 해요. 공식 공지에 따르면 이 완전한 대화 수준 도구 통합은 deepseek-flash(DeepSeek-V4.1-Flash)가 담당해요. APIYI 문서 설명에 따르면 Harness, Claude Code 같은 클라이언트에서 게이트웨이를 거쳐 이런 내장 검색을 호출하는 호환 작업은 아직 후속 계획 단계에 있으며, 현재 경로 A를 사용하려면 DeepSeek 공식 API에 직접 연결해야 해요.
4.3 APIYI 독립 Search / Fetch 연동
APIYI는 2026년 10월 21일에 DeepSeek Search & Fetch 독립 도구 인터페이스를 출시했으며, 각각 deepseek-search와 deepseek-fetch에 해당해요. Search는 구조화된 검색 결과를 반환하고, Fetch는 지정한 웹페이지를 가져와 Markdown 본문을 반환해요. 요청할 때 모델 ID를 전달할 필요가 없고 모델 Token도 소모하지 않으며, 성공한 호출 횟수를 기준으로 과금돼요.
다음 예시는 먼저 검색한 뒤, 검색 결과에서 1위인 웹페이지를 가져와요:
import os
import requests
BASE = "https://api.apiyi.com/v1/tools" # APIYI 독립 도구 인터페이스
headers = {"Authorization": f"Bearer {os.environ['APIYI_API_KEY']}"}
search = requests.post(
f"{BASE}/search",
headers=headers,
json={"query": "DeepSeek Harness 插件", "count": 5},
timeout=60,
)
search.raise_for_status()
results = search.json()["results"]
if results:
url = results[0]["url"]
fetch = requests.post(
f"{BASE}/fetch",
headers=headers,
json={"url": url},
timeout=60,
)
if fetch.ok:
print(fetch.json()["content"])
토큰 그룹은 특히 주의해야 해요. default 및 svip 그룹은 이 두 인터페이스를 호출할 수 있지만, ClaudeCode 그룹 토큰은 직접 호출할 수 없어요. 문서에는 503을 반환한 사례가 기록되어 있죠. APIYI 문서의 자체 테스트에 따르면 Search가 5개 결과를 반환하는 데 약 1.8초가 걸렸고, 동시 요청 20개가 모두 200을 반환했어요. Fetch는 접근할 수 없는 페이지에 접속하면 실패를 반환하며 과금하지 않아요. 이 데이터는 플랫폼 자체 테스트에서 나온 것이며, 실제 성능은 네트워크와 대상 사이트의 영향을 받아요. 가격은 문서에 사이트 내 가격이 1,000회당 $0.90으로 기재되어 있고, 충전 보너스가 더해지면 실제 결제 금액은 더 낮아져요. 구체적인 금액은 콘솔을 기준으로 확인해 주세요.
Harness의 Agent가 이 로직을 스스로 활용하게 하려면, 이를 도구 플러그인으로 만들어야 해요. Harness 플러그인은 TypeScript로 작성하며, 컨텍스트 객체 ctx를 통해 도구를 등록해요. 플러그인이 언로드되면 프레임워크가 등록된 도구와 이벤트를 자동으로 정리해요. 구현할 때는 search와 fetch를 두 개의 독립 도구로 등록해, 모델이 먼저 결과 목록을 받은 다음 어떤 페이지를 가져올지 결정하도록 하는 게 좋아요.
💡 기술 제안: 독립 Search / Fetch는 모델과 분리되어 있어, 동일한 검색 결과를 GPT, Claude, DeepSeek 등 서로 다른 모델에 넘겨 처리할 수 있어요. APIYI apiyi.com을 통해 하나의 키로 모델 호출과 검색 도구를 함께 관리할 수 있으므로, Harness에서 같은 자료를 바탕으로 여러 모델의 답변 품질을 비교하기 쉬워요.
5 DeepSeek Harness 멀티 모델 Agent는 어떻게 설계해야 할까
5.1 작업에 따라 다른 모델 선택하기
멀티 모델 연동의 가치는 작업별로 모델을 배분하는 데 있어요. 코딩 Agent에는 코드에 강한 모델을 쓰고, 문서 정리나 요약·리라이팅처럼 자주 반복되는 작업에는 비용이 낮은 모델이 어울려요. 반면 스크린샷 분석이나 차트 이해는 이미지 입력을 지원하는 비전 모델을 골라 Input Type에서 이미지를 체크해야 하죠.
DeepSeek 공식 모델을 예로 들면, DeepSeek-V4.1-Flash는 이미지 이해를 지원하지만 DeepSeek-V4-Pro는 지원하지 않고, 두 모델의 가격도 몇 배 차이가 나요. Harness에서 이 둘을 같은 제공자 아래의 두 개 Model ID로 등록해 두고, 작업에 따라 세션에서 전환하면 효과와 비용을 함께 챙길 수 있어요.
5.2 DeepSeek Harness 모델 호출과 검색 능력을 계층으로 나눠 관리하기

권장 구조는 세 계층으로 나뉘어요. 실행 계층은 Harness가 작업 루프, 컨텍스트 압축, 플러그인 로딩, 권한 제어를 맡고, 모델 계층은 API 게이트웨이가 프로토콜 변환, 모델 라우팅, 과금을 처리해요. 도구 계층은 독립된 Search / Fetch 같은 인터페이스가 외부 정보를 제공하죠. 세 계층은 각각 교체가 가능해서, 모델을 바꾸려면 Model ID만 고치면 되고 검색 서비스를 바꾸려면 도구 플러그인만 교체하면 되며 실행 로직은 그대로 둘 수 있어요.
계층 분리는 보안 측면에서도 이점이 있어요. 텐센트 주췌(朱雀) 연구소가 Harness를 대상으로 한 통제 평가에 따르면, 웹 페이지나 파일, Skills 같은 비신뢰 콘텐츠가 간접 프롬프트 주입을 통해 Agent 동작에 영향을 줄 수 있다고 해요. 도구 계층과 실행 계층을 분리하면 검색 결과가 컨텍스트로 들어오기 전, 그리고 민감한 도구가 실행되기 전에 통합된 필터링과 확인 단계를 넣을 수 있어요.
5.3 DeepSeek Harness 실제 배포 제안
- 모델 설정: 하나의 프로토콜에는 하나의 제공자를 대응시키고, Provider ID는 소문자로 쓰며 한 번 정해 두세요. 모델 ID는 반드시 게이트웨이 콘솔에서 복사해야 해요.
- 키 관리: Harness는 키를
$DSH_HOME/.credentials.yaml에 저장하니, 설정 파일에는 환경 변수만 참조하도록 해서 평문 Key가 공유 설정이나 코드 저장소에 들어가지 않게 하세요. - 호환성 테스트: 새 모델을 붙일 때마다 일반 대화, 사고(thinking) 끄기, 긴 출력, 이미지 입력을 차례로 검증하고, 나온 오류에 따라
compat파라미터를 켜세요. - 도구 호출: 플러그인 개수를 관리해야 해요. 커뮤니티 피드백을 보면 플러그인을 열 개 이상 설치했을 때 컨텍스트 오버플로와 토큰 소모 증가가 나타날 수 있었어요. 검색 도구는 설명을 간결하게 유지할수록 더 안정적이에요.
- 비용 기록: 모델 토큰과 도구 호출은 따로 과금되니, 게이트웨이 백엔드에서 별도로 집계하는 걸 권해요. APIYI apiyi.com 콘솔에서는 Key 기준으로 사용량을 볼 수 있어서, Agent마다 별도 Key를 발급해 비용을 구분해 추적하기 좋아요.
또 Harness를 업그레이드하기 전에는 $DSH_HOME 아래 설정을 먼저 백업하세요. 한 번의 버전 업그레이드 후 서드파티 플러그인 설정이 유실되어 복구에 몇 시간이 걸린 사례가 커뮤니티에 기록되어 있어요.
자주 묻는 질문 FAQ
Q1: DeepSeek Harness는 DeepSeek 모델만 사용할 수 있나요?
Harness는 사용자 정의 모델 API를 통해 네 가지 프로토콜 중 하나와 호환되는 서비스라면 무엇이든 연결할 수 있어요. OpenAI, Claude, Gemini 계열은 물론 각종 API 게이트웨이와 자체 구축 모델 서비스도 포함되죠. DeepSeek 공식 모델은 그중 하나의 옵션일 뿐이에요.
Q2: 같은 게이트웨이인데 왜 여러 개의 공급자를 만들어야 하나요?
Harness는 하나의 공급자에 하나의 프로토콜만 바인딩하도록 정해져 있어요. APIYI는 OpenAI 호환, Anthropic, Gemini 세 가지 진입점을 동시에 제공하는데, GPT, Claude, Gemini를 각각 네이티브 프로토콜로 호출하려면 공급자를 세 개 만들어야 하고 Base URL은 각각 `/v1`, 루트 도메인, `/v1beta`가 됩니다.
Q3: 내가 입력해야 할 모델 ID가 무엇인지 어떻게 확인하나요?
먼저 “사용 가능한 모델 가져오기” 기능을 사용해 보세요. 읽어오지 못할 때는 APIYI apiyi.com 콘솔의 모델 목록에서 정확한 이름을 복사해 수동으로 추가하면 됩니다. 모델 ID는 대소문자와 버전 접미사를 구분하므로, 조금이라도 다르면 UNKNOWN_MODEL이나 게이트웨이 오류가 발생해요.
Q4: APIYI를 통해 연결한 뒤 deepseek_web_search를 바로 사용할 수 있나요?
현재 APIYI는 DeepSeek 독립 Search / Fetch 인터페이스를 지원하고 있으며, Harness 같은 클라이언트를 통해 모델 내장 검색을 호출하는 호환 작업은 여전히 계획 중이에요. 현 단계에서는 APIYI의 `/v1/tools/search`와 `/v1/tools/fetch`를 Agent 도구로 감싸서 쓰는 방법을 권장하며, 내장 검색이 필요할 때는 DeepSeek 공식 API에 직접 연결하세요.
Q5: 검색 인터페이스는 503을 반환하는데 대화는 완전히 정상이라면, 원인은 무엇인가요?
가장 흔한 원인은 토큰 그룹이에요. ClaudeCode 그룹의 토큰은 독립 도구 인터페이스를 직접 호출할 수 없으므로, default 또는 svip 그룹의 Key로 바꾸면 됩니다. APIYI apiyi.com 백엔드에서 검색 도구 전용으로 해당 그룹의 토큰을 별도 생성해 모델 호출용 Key와 분리해 관리할 수도 있어요.
Q6: DeepSeek Harness의 멀티 모델 연결에는 어떤 제약이 있나요?
Harness는 아직 개발자 프리뷰 버전이라 구성 구조가 버전에 따라 달라질 수 있어요. 각 게이트웨이마다 Responses, 추론 파라미터, 도구 프로토콜의 투과 지원 수준이 달라서 모델별로 하나하나 검증해야 하죠. 플러그인이 너무 많으면 컨텍스트와 토큰 비용이 올라가고, 복잡한 작업의 결과 품질도 플러그인 설정과 실행 과정 관리에 따라 달라집니다.
요약
DeepSeek Harness의 오픈 모델 적응 메커니즘을 활용하면, 하나의 Agent 프레임워크가 통합 게이트웨이를 통해 여러 벤더의 모델을 호출할 수 있어요. 실제로 적용할 때는 다음 몇 가지를 기억하세요.
- 프로토콜이 Provider를 결정해요: 프로토콜 하나당 Provider 하나를 만들고, Base URL의 버전 접두사는 프로토콜과 정확히 대응해야 해요.
- 모델 ID는 게이트웨이에서 그대로 복사해요: 콘솔에서 복사하고, 목록을 불러올 수 없다면 직접 추가하세요.
- 오류에 맞춰 호환 파라미터를 켜요: developer 역할,
max_tokens필드, DeepSeek 사고 형식 이 세 가지만으로도 대부분의 “연결은 되지만 사용은 안 되는” 문제를 해결할 수 있어요. - 웹 검색 기능은 별도로 계획해요: 내장 검색은 DeepSeek 공식 API를 사용하고, 독립적인 Search / Fetch는 게이트웨이를 거쳐 호출한 뒤 도구로 래핑할 수 있어요.
- 계층 분리와 거버넌스: 실행 계층, 모델 계층, 도구 계층을 분리하고 키, 버전, 비용은 각각 따로 관리해요.
먼저 모델 하나로 “스크립트 검증 → Harness 구성 → 간단한 대화” 흐름을 끝까지 확인한 뒤, 더 많은 모델과 검색 도구를 단계적으로 추가하는 걸 권장해요. APIYI apiyi.com에서 무료 테스트 크레딧을 받아 하나의 Key로 다중 모델과 Search / Fetch 전체를 검증해 보세요.
📚 참고 자료
- DeepSeek Harness 모델 구성 문서: 사용자 정의 프로바이더 필드와 compat 호환 파라미터
- 링크:
deepseek-harness.github.io/deepseek-harness/guide/providers -
설명: supportsDeveloperRole, maxTokensField, thinkingFormat의 공식 설명
-
DeepSeek Harness GitHub 저장소: 소스 코드, Releases 및 시작 방법
- 링크:
github.com/deepseek-ai/deepseek-harness -
설명: 버전 업데이트와 개발자 프리뷰 단계 안내
-
DeepSeek 웹 도구 문서: deepseek_web_search와 deepseek_read_url
- 링크:
api-docs.deepseek.com/zh-cn/guides/web_tools/ -
설명: 내장 검색의 선언 방식, 제한 및 과금 기준
-
APIYI Base URL 구성 가이드: 세 가지 프로토콜 경로 설명
- 링크:
help.apiyi.com/apiyi-base-url-v1-claude-gemini-endpoint-config-guide.html -
설명:
/v1, 루트 도메인,/v1beta의 사용 시나리오 -
APIYI DeepSeek Search & Fetch 문서: 독립 도구 인터페이스와 그룹 요구 사항
- 링크:
docs.apiyi.com/api-capabilities/deepseek-search-fetch/overview - 설명: 요청 파라미터, 토큰 그룹 및 과금 안내
작성자: APIYI 기술 팀
기술 문의: 구성 중 문제가 생기면 APIYI apiyi.com 홈페이지를 통해 문의해 주세요. 더 많은 인터페이스 설명은 docs.apiyi.com 문서 센터에서 확인할 수 있어요.
