CH 06 · 모델과 추론 강도 설정
본장 목표
"어떤 모델을 쓸지"와 "얼마나 사고하게 할지"라는 두 손잡이를 제대로 설정합니다. 먼저 모델 호출에 필요한 세 가지(API Key / Base URL / Model ID)를 이해하고, 그다음 구성 파일을 읽어 기본 모델을 바꾸고 추론 강도를 조정한 뒤, 마지막으로 서드파티 모델을 꽂는 법을 익힙니다.
먼저 이해하기: 세 가지 개념 — API Key / Base URL / Model ID
어떤 도구로 대형 모델을 호출하든, 한 번의 요청에 다음 세 가지가 실립니다. — API Key(누구인가), Base URL(어디로 갈 것인가), Model ID(어떤 모델을 쓸 것인가).
하나씩 풀어 봅니다.
- API Key:
sk-접두사가 붙은 문자열로, 모델 플랫폼에서의 "신분증"입니다. 요청에 실려 플랫폼이 누구인지, 어느 계정으로 요금을 매길지 판단합니다. 비밀번호이므로 유출하지 마시고, Git 저장소에 커밋하지 마십시오. 참고로,sk-접두사는 OpenAI 호환 생태계 전반의 관용 형식이며, DeepSeek를 비롯한 많은 국내 플랫폼과 자체 게이트웨이도 모두 이 형식을 따릅니다. - Base URL: 모델의 "주소", 즉 API 서비스 엔드포인트입니다. 모든 요청은 이 주소로 갑니다.
- Model ID: 모델의 이름으로, 정확히 어느 모델을 쓸지 지정합니다. 요청에
deepseek-v4-flash-vision-exp라고 적혀 있으면 비전 버전을 쓰고,deepseek-v4-pro이면 플래그십입니다.
이 세 값 모두 모델 플랫폼 자체에서 가져오는 것이지, dsh가 만든 것이 아닙니다. DeepSeek를 예로 들어 어디서 가져오는지 보겠습니다.
- API Key: DeepSeek 오픈 플랫폼을 열고, 회원가입 후 로그인한 다음, 콘솔 → API Keys → API key 생성(Create API key) 으로 가서 이름을 짓고 생성 버튼을 누른 뒤 즉시 복사해 두십시오. Key는 생성 직후 한 번만 전체가 표시되고, 그 이후에는 페이지에 마스킹된 설명만 남습니다.
- Base URL: DeepSeek 공식 문서는 OpenAI 호환 엔드포인트가
https://api.deepseek.com이라고 명확히 밝힙니다(Anthropic 호환 엔드포인트는https://api.deepseek.com/anthropic). - Model ID: 공식 API 문서의 모델 목록에서 찾으면 됩니다. 모델 선택기에서 본 그것과 동일합니다(
deepseek-v4-pro/deepseek-v4-flash/deepseek-v4-flash-vision-exp).
나중에 서드파티 모델을 꽂을 때도 똑같다는 사실을 깨닫게 됩니다. 값만 다를 뿐입니다.
구성 파일의 위치: $DSH_HOME/settings.yaml
dsh의 전역 구성은 단 한 파일입니다. C:\Users\<사용자 이름>\.dsh\settings.yaml. 제 컴퓨터의 모습은 이렇습니다.
ui-onboarding:
welcomeNoticeVersion: 2026-08-13.1
agent-default-model:
provider: deepseek-official
model: deepseek-v4-flash-vision-exp
reasoningEffort: high이 파일은 Web UI에서 모델과 추론 강도를 바꿀 때 그 변경이 도착하는 곳입니다. UI에서 무엇을 바꾸든 결국 여기에 기록됩니다. 세 필드가 각각 하나씩을 담당합니다.
| 필드 | 역할 | 제 값 |
|---|---|---|
provider | 어느 제공자를 통해 라우팅할지 | deepseek-official(DeepSeek 공식) |
model | 새 세션의 기본 모델 | deepseek-v4-flash-vision-exp |
reasoningEffort | 기본 추론 강도 | high |
세 모델 중 어떻게 고를까
공식 DeepSeek 어댑터는 기본적으로 세 모델을 노출하며, 각각 컨텍스트 윈도우는 1M 토큰입니다.
| Model ID | 포지셔닝 |
|---|---|
deepseek-v4-pro | 플래그십, 복잡하고 품질이 중요한 작업, 능력은 가장 뛰어나지만 비용도 큼 |
deepseek-v4-flash | 빠르고 경제적, 일상 작업용 |
deepseek-v4-flash-vision-exp | 비전 버전: 이미지 읽기, 스크린샷 보기 가능. 순수 텍스트는 flash와 동급 |
한 가지 디테일. Model ID는 프로토콜에 그대로 전달되므로, 공식 팀이 새 모델을 출시할 때 별도로 등록할 필요 없이 새 ID를 구성에 채워 넣으면 됩니다.
추론 강도: off / low / high / max
추론 강도는 모델이 행동에 나서기 전에 얼마나 "사고"할지를 정합니다. DeepSeek 공식 모델은 네 단계를 제공합니다. Web UI에서 입력란 오른쪽의 모델 버튼을 누르면 이 네 단계를 보고 전환할 수 있습니다(로컬 실측. 기본 선택은 High).
| 단계 | 동작 |
|---|---|
off | 사고 비활성(thinking: disabled), 가장 빠르고 저렴 |
low | 가벼운 사고 |
high(기본) | 깊은 추론. Agent 작업에 적합 |
max | 가장 강한 사고 강도. 가장 어려운 작업 전용 |
공식 기본값은 high입니다. 단계는 시간과 비용에 직접 영향을 줍니다. 사고를 켠 단계는 약간 느리고 비싸지만 복잡한 작업에서 더 신뢰할 만하고, off는 사고를 하지 않으니 단순 Q&A가 즉시 돌아옵니다. 단계를 고를 때의 원칙은 하나. 작업이 어려울수록 단계를 높게.
변경 방법: Web UI 또는 파일 직접 편집
두 방법 모두 결국 settings.yaml에 도달합니다.
- Web UI:
설정 → 모델(Settings → Models). 키 저장, 설정된 모델 확인, 제공자 추가. 모델 선택기에서 고른 모델이 새 세션의 기본값이 됩니다. 이미 요청을 보낸 세션은 시작 시 사용 중이던 모델을 그대로 유지하며, 기본값을 바꾼다고 따라 바뀌지 않습니다.
- 파일을 직접 편집:
agent-default-model의 세 필드를 바꾸거나,llm-deepseek:섹션을 추가해 더 많은 필드를 덮어쓰십시오(사용자 정의 제공자 꽂을 때 사용).
적용 규칙: 변경은 다음 요청부터 즉시 적용되며, 서비스 재시작은 필요 없습니다.
서드파티 모델 설정
지금까지는 DeepSeek 공식 설정이었습니다. 바로 여기에 dsh만의 차별점이 있습니다. 아무 모델이나 꽂을 수 있으며, 자사 모델에 종속되지 않습니다. 공식 어댑터는 기본으로 DeepSeek일 뿐이고, Anthropic, OpenAI, OpenAI 호환 게이트웨이, 심지어 로컬 모델까지 완전히 꽂을 수 있습니다. 반면 Codex 같은 제품은 모델 세트가 고정되어 있어, 제공자를 바꾸려면 공식 팀이 열어 주기를 기다려야 합니다. dsh에서 서드파티를 꽂는 방법은 두 가지입니다.
방법 1: 제공자 추가(기존 디렉터리 사용)
설정 → 모델 페이지에는 제공자 추가(Add Provider) 항목이 있고, 거기에는 공식 "디렉터리"들이 한 묶음 있습니다. Anthropic, OpenAI 등 기존 디렉터리를 고릅니다. 엔드포인트와 프로토콜은 이미 설정되어 있습니다. 추가 후 다음 세 단계 양식을 따릅니다.
- 제공자 선택: "Provider" 드롭다운을 클릭해 꽂고 싶은 제공자(예: minimax-cn)를 선택합니다.
- API Key 입력: 해당 플랫폼의 Key를 "API Key" 칸에 붙여넣습니다. 마스킹 표시, 쓰기 전용.
- 사용 가능한 모델 가져오기: "사용 가능한 모델 가져오기"를 눌러 그 제공자의 모델 디렉터리를 받아온 다음, 목록에서 원하는 Model ID를 골라 사용합니다.
저장 후 그 제공자의 모델이 모델 선택기에 나타나 평소처럼 사용할 수 있습니다.
방법 2: 사용자 정의 제공자 추가(자체 게이트웨이 / 로컬 모델)
dsh에 해당 플랫폼이 사전 설치되어 있지 않다면 사용자 정의 제공자 추가(Add Custom Provider) 를 사용하십시오. 채워야 할 것은 본장 첫 부분의 세 가지에 하나를 더한 것입니다.
| 필드 | 무엇 | 예시 |
|---|---|---|
| Provider ID | 이 제공자의 고유 ID(소문자, 한 번 정하면 영구) | my-gateway |
| API 주소 | Base URL, 모델 서비스의 주소 | https://your-gateway-address |
| API 프로토콜 | 어떤 포맷으로 대화할지(OpenAI / Anthropic 호환 등) | openai-completions |
| Key | API Key, 인증 자격 | sk-... |
| Model | 최소 하나의 Model ID 입력 | deepseek-v4-flash |
저장 후 이 사용자 정의 제공자가 모델 목록에 나타나 평소처럼 사용할 수 있습니다. 몇 가지 참고.
- Provider ID는 한 번 정하면 영구이므로 함부로 바꾸지 마십시오. 이후 구성이 이 ID를 참조합니다.
- 로컬 모델 / 자체 게이트웨이의 경우 API 주소를 자체 서비스로 가리키고 Key 칸에는 그 서비스의 키를 채워 넣거나(필요한 경우 그 서비스의 규약대로 자리표시자를 남겨 두십시오).
- 사용자 정의 모델이 비전 모델(이미지를 받는)이라면 Model ID만 채우는 것으로는 부족합니다. 공식 요건은 추가로 이미지 입력을 지원함을 선언해야 한다는 것입니다. settings.yaml에서 해당 제공자 항목에
input: [text, image]한 줄을 추가하십시오. 그렇지 않으면 이미지가 유효하지 않은 입력으로 거부됩니다.
키와 자격 증명
(CH 03에서) 입력한 Key 카드의 이면에는 두 가지 메커니즘이 있습니다.
- Key는 쓰기 전용:
설정 → 모델에서 저장 후 페이지에는 마스킹된 설명만 보이며, 평문은C:\Users\<사용자 이름>\.dsh\.credentials.yaml에만 기록됩니다. settings.yaml에는 자격 참조만 저장될 뿐 평문은 절대 들어가지 않습니다. - 해결 순서: 요청 시점에 먼저 자격 저장소를 보고, 없으면 환경 변수(기본
DEEPSEEK_API_KEY)를 폴백으로 사용합니다. 둘 다 없으면MISSING_CREDENTIAL을 받습니다.
문제 해결 치트시트
구성 관련 오류는 손에 꼽을 정도입니다. 해당 항목을 찾으십시오.
| 오류 | 의미 | 해결 |
|---|---|---|
MISSING_CREDENTIAL | 키 미설정 | Models 페이지에서 키 저장, 또는 참조되는 환경 변수 설정 |
INVALID_CREDENTIAL | Key 형식 오류 | 입력한 Key 확인 |
UNKNOWN_MODEL | 모델이 없거나 설정되지 않음 | 설정된 모델 선택 |
UNSUPPORTED_REASONING_EFFORT | 지원하지 않는 추론 강도 | off / low / high / max 중 하나 사용 |
| 사용 가능한 모델 가져오기 401 반환 | Key가 틀림 | Key 확인. 모델 디스커버리는 OpenAI 호환 GET /models 엔드포인트를 호출 |
이 장에서 배운 것
아래 항목들을 스스로 완수할 수 있으면 합격입니다.
- [ ] 세 가지 개념 API Key / Base URL / Model ID를 설명하고, 그것들을 어디서 얻는지(DeepSeek를 예로) 말할 수 있다
- [ ] settings.yaml의 위치와
agent-default-model의 세 필드가 무엇을 뜻하는지 말할 수 있다 - [ ] DeepSeek Model ID 세 가지의 포지셔닝을 말할 수 있다
- [ ] 추론 강도 네 값(off / low / high / max)과 기본값, 선택 원칙을 말할 수 있다
- [ ] 모델/강도를 바꾼 뒤 다음 요청부터 적용되며 재시작이 필요 없다는 것을 알고 있다
- [ ] 서드파티 모델을 꽂는 두 방법을 알고 있다: 제공자 추가(기존 디렉터리, Key 입력, Model ID 사용) vs 사용자 정의 제공자 추가(Provider ID / API 주소 / 프로토콜 / 키 / 모델)
- [ ] Key가 어디에 저장되며, settings에 평문이 남지 않는 이유를 알고 있다
- [ ] 문제 해결 표를 써서
MISSING_CREDENTIAL,UNKNOWN_MODEL같은 오류를 특정할 수 있다