공식 안내에 따르면 모델 설정 변경은 서버를 다시 시작하지 않아도 다음 요청부터 적용됩니다. 따라서 딥시크 하니스 맞춤 모델 서비스 연결은 처음부터 복잡한 설정을 늘리는 작업이 아니라, 기본 제공 경로로 충분한지 먼저 판단한 뒤 필요한 경우에만 맞춤 제공자를 추가하는 방식이 안전합니다. 공식 저장소와 설정 안내서는 개발자 미리보기 상태이므로, 연결 전후에 현재 문서와 실제 화면을 함께 확인해야 합니다. 공식 저장소와 공식 모델 설정 안내서를 기준으로 검증합니다.
판단 기준: 공식 딥시크 API나 설치된 목록에 있는 서비스라면 기본 경로를 우선 사용합니다. 회사 게이트웨이, 자체 운영 서버, 목록 밖 모델처럼 기본 목록으로 설명되지 않는 대상일 때만 맞춤 제공자를 추가합니다.
이 글은 회사 모델 게이트웨이를 통해 하니스를 운영하려는 플랫폼 엔지니어, 오픈에이아이 호환 에이피아이를 제공하는 자체 운영 모델 팀, 기존 세션을 건드리지 않고 모델 경로를 추가하려는 에이전트 개발자를 위한 내용입니다. 단순히 모델 이름을 바꾸는 목적이라면 맞춤 설정을 새로 만들 필요가 없을 수 있습니다.
마지막 업데이트: 2026년 8월 18일. 데이터와 설정 흐름은 같은 날짜의 공식 저장소, 모델 제공자 안내서, 설정 목록을 기준으로 확인했습니다.
00먼저 기본 경로와 맞춤 제공자를 구분합니다
딥시크 하니스에는 설치된 서비스 목록을 이용하는 제공자와 사용자가 직접 입력하는 맞춤 제공자가 구분되어 있습니다. 공식 딥시크 API는 기본 딥시크 경로로 처리하는 편이 관리하기 쉽습니다. 설치된 제공자 목록에 이미 회사가 사용하는 서비스가 있다면, 같은 대상을 맞춤 제공자로 다시 등록하면 자격 증명과 모델 선택 항목이 중복될 수 있습니다.
| 선택 대상 | 기본 경로 | 맞춤 제공자 | 판단 기준 |
|---|---|---|---|
| 공식 딥시크 API | 적합 | 보통 불필요 | 공식 키와 기본 모델만 필요할 때 |
| 설치된 제공자 목록의 서비스 | 적합 | 보통 불필요 | 주소, 통신 방식, 모델 목록이 이미 제공될 때 |
| 회사 내부 모델 게이트웨이 | 부적합할 수 있음 | 적합 | 내부 주소와 별도 인증을 사용할 때 |
| 자체 운영 모델 서버 | 부적합할 수 있음 | 적합 | 설치 목록에 없고 직접 모델 아이디를 입력해야 할 때 |
| 목록 밖 외부 서비스 | 부적합할 수 있음 | 적합 | 오픈에이아이 호환 에이피아이를 제공하지만 기본 목록에 없을 때 |
오픈에이아이 호환 에이피아이라고 해서 자동으로 동작한다고 단정해서는 안 됩니다. 하니스가 실제로 사용하는 통신 방식, 인증 헤더, 모델 조회 방식, 도구 호출 형식을 모두 확인해야 합니다. 딥시크 공식 API의 기본 주소와 인증 키, 모델 이름은 공식 에이피아이 안내에서 확인할 수 있지만, 다른 서비스의 동작까지 보장한다는 뜻은 아닙니다.
01첫 단계에서 프로바이더 아이디와 연결 정보를 고정합니다
맞춤 제공자를 만들 때는 표시 이름보다 프로바이더 아이디를 먼저 결정해야 합니다. 공식 안내에 따르면 이 아이디는 요청, 저장된 세션, 새 세션의 기본 모델, 자격 증명 참조에 사용되며 저장 후에는 임의로 바꾸는 방식이 지원되지 않을 수 있습니다. 이름을 바꿔야 한다면 새 제공자를 만들고 기존 제공자를 정리하는 절차가 필요합니다.
다음 항목을 회사 내부 문서에 먼저 기록하는 것이 좋습니다.
- 소문자로만 구성한 고정 프로바이더 아이디
- 화면에 표시할 설명 이름
- 베이스 유알엘과 필요한 경로
- 사용할 에이피아이 통신 방식
- 자격 증명 저장 방식 또는 환경 변수 참조
- 실제 호출할 모델 아이디
- 모델 목록 조회를 지원하는지 여부
화면의 항목명과 설정 파일의 키는 개발자 미리보기 기간에 바뀔 수 있으므로, 오래된 블로그의 설정 예시를 그대로 복사하지 않아야 합니다. 현재 안내서에는 맞춤 제공자에 베이스 유알엘, 통신 방식, 자격 증명, 하나 이상의 모델을 입력하도록 되어 있습니다. 지원 대상은 공식 설정 목록에서 다시 대조합니다.
providers:
company-gateway:
baseURL: https://gateway.example/v1
api: openai-completions
apiKeyEnv: COMPANY_GATEWAY_KEY
models:
- id: company-model
위 예시는 구조를 이해하기 위한 형태입니다. 실제 키 이름과 지원 범위는 글을 확인하는 날짜의 공식 화면과 설정 목록을 기준으로 대조해야 합니다. 특히 베이스 유알엘에 이미 버전 경로가 포함되어 있는지, 하니스가 요청 경로를 다시 붙이는지 확인하지 않으면 주소가 중복될 수 있습니다.
02저장 후 모델 발견 결과를 먼저 판정합니다
저장에 성공했다는 표시만으로 모델을 호출할 수 있다고 판단하면 안 됩니다. 맞춤 제공자는 모델 목록을 자동으로 가져오거나, 모델 목록을 제공하지 않는 서버에 대해 모델 아이디를 직접 입력해야 할 수 있습니다. 모델 목록을 조회한 뒤 선택한 모델을 저장하는 흐름은 공식 제공자 안내서의 현재 절차를 기준으로 확인합니다.
실패 신호는 다음처럼 구분합니다.
- 인증 실패: 모델 목록 조회가 401로 끝나면 먼저 키의 값, 권한, 전달 위치를 확인합니다.
- 모델 목록 없음: 서버가 모델 목록 경로를 제공하지 않으면 자동 발견을 계속 반복하지 말고, 실제 서비스가 요구하는 모델 아이디를 수동 입력합니다.
- 모델 아이디 불일치: 목록에는 보이지만 첫 요청에서 알 수 없는 모델 오류가 나오면 하니스에 저장한 아이디와 게이트웨이가 받는 아이디가 같은지 대조합니다.
- 자격 증명 참조 누락: 저장된 키 자체가 아니라 참조만 설정된 경우, 참조하는 환경 변수가 실행 프로세스에 전달되는지 확인합니다.
모델 목록 조회가 401을 반환할 때 키를 바로 새로 발급하기보다, 게이트웨이가 요구하는 인증 방식과 하니스의 인증 방식이 같은지 먼저 확인해야 합니다. 모델 조회 주소와 실제 채팅 요청 주소가 서로 다른 인증 정책을 사용하는 환경도 있으므로 두 요청을 분리해서 기록합니다.
03두 번째 단계에서 새 세션으로 최소 요청을 검증합니다
모델 목록이 정상적으로 보이면 중요한 저장소를 바로 열지 말고, 격리된 작업 공간과 새 세션을 사용합니다. 검증은 다음 순서로 진행합니다.
- 빈 테스트 작업 공간을 선택합니다.
- 새 세션에서 짧은 텍스트 요약 요청을 보냅니다.
- 실제 응답이 반환되는지와 응답 지연, 실패 메시지를 기록합니다.
- 새 세션을 다시 만들어 선택된 모델이 기본값으로 잡히는지 확인합니다.
- 읽기 전용에 가까운 도구 호출을 하나만 추가합니다.
- 도구 호출의 인자 형식과 도구 실행 후 이어지는 모델 응답을 확인합니다.
- 실패하면 맞춤 제공자를 바로 수정하지 말고, 직전에 검증된 기본 경로로 되돌려 원인이 모델 서비스인지 하니스 설정인지 분리합니다.
도구 호출은 일반 텍스트 요청보다 확인할 항목이 많습니다. 모델이 도구 설명을 받는지, 호출 이름과 인자를 올바르게 생성하는지, 게이트웨이가 해당 요청 형식을 그대로 전달하는지 각각 확인해야 합니다. 딥시크 에이피아이의 도구 호출 형식은 공식 도구 호출 안내에서 확인할 수 있지만, 맞춤 게이트웨이가 같은 형식을 보존한다는 뜻은 아닙니다.
04저장 후 모델을 찾지 못할 때 조회 경로를 나눠 봅니다
맞춤 제공자를 저장했는데 모델이 선택 목록에 나타나지 않는 경우는 보통 세 갈래입니다.
첫째, 모델이 제공자 설정에 저장되지 않았습니다. 자동 발견 결과에서 모델을 선택하지 않았거나, 수동 입력 후 저장을 완료하지 않았는지 확인합니다.
둘째, 모델 아이디가 실제 서버의 아이디와 다릅니다. 화면에 표시되는 별칭과 요청에 필요한 내부 아이디가 다를 수 있으므로 게이트웨이 문서와 요청 기록을 대조해야 합니다.
셋째, 프로바이더 아이디가 바뀌었습니다. 기존 세션이나 기본값이 이전 아이디를 참조하고 있다면 새 제공자를 만든 뒤 새 세션에서 다시 선택해야 합니다. 이름만 같게 바꾸는 방식으로는 이전 참조가 자동으로 이전되지 않습니다.
401이 반복되면 다음 항목을 차례로 확인합니다.
- 게이트웨이가 요구하는 인증 방식과 하니스의 인증 방식이 같은지
- 키가 만료되었거나 특정 경로 접근 권한을 갖고 있는지
- 모델 조회 주소와 실제 채팅 요청 주소가 같은 인증 정책을 사용하는지
- 실행 중인 하니스 프로세스가 새 환경 변수를 읽고 있는지
05세 번째 단계에서 기존 세션과 새 기본값을 분리합니다
모델 선택 화면에서 새 모델을 기본값으로 지정해도, 이미 요청을 보낸 세션이 자동으로 새 모델로 바뀐다고 보면 안 됩니다. 공식 안내서에 따르면 요청을 이미 보낸 세션은 자체 기록에 저장된 모델을 유지하고, 새로 선택한 모델은 새 세션의 기본값에 영향을 줍니다. 제공자를 삭제해 기존 세션의 모델이 사라지면 모델을 다시 선택하라는 표시가 나타날 수 있습니다.
따라서 운영 전환은 다음처럼 진행하는 편이 안전합니다.
- 기존 세션은 재현과 비교를 위해 보존합니다.
- 새 모델은 새 세션에서 텍스트 요청부터 검증합니다.
- 도구 호출까지 통과한 뒤에만 새 작업을 시작합니다.
- 기존 세션에서 설정을 반복 수정하며 결과를 덮어쓰지 않습니다.
- 제공자 삭제 전에는 현재 세션이 참조하는 모델과 회귀 경로를 기록합니다.
이 방식은 모델 변경 문제와 세션 기록 문제를 분리해 줍니다. 하니스의 실행 환경과 원격 접속 관리가 함께 필요하다면 NUKCLOUD 도움말에서 별도 환경 운영 절차를 확인할 수 있습니다.
06네 번째 단계에서 변경 기록과 회귀 경로를 만듭니다
안정적으로 동작한 뒤에는 설정을 자주 바꾸는 것보다 변경 기준을 정하는 일이 중요합니다. 다음 항목을 한 묶음으로 기록합니다.
- 프로바이더 아이디
- 베이스 유알엘
- 통신 방식
- 자격 증명 참조 이름
- 모델 아이디
- 모델 조회 성공 여부
- 텍스트 요청 성공 여부
- 도구 호출 성공 여부
- 실패 시 되돌릴 기본 경로
딥시크 하니스는 개발자 미리보기 상태이므로 업그레이드 뒤에 같은 설정이 그대로 유지된다고 가정하면 안 됩니다. 공식 저장소가 호환성을 깨는 변경 가능성을 명시하고 있기 때문에, 하니스나 모델 게이트웨이를 바꿀 때마다 최소 텍스트 요청과 제한된 도구 호출을 다시 실행해야 합니다.
최종 확인 목록
- [ ] 공식 경로로 충분한지 먼저 판정했습니다.
- [ ] 프로바이더 아이디를 저장 전에 확정했습니다.
- [ ] 베이스 유알엘과 요청 경로가 중복되지 않습니다.
- [ ] 인증 키 또는 자격 증명 참조를 실행 프로세스에서 확인했습니다.
- [ ] 모델 목록 자동 조회 결과를 실제 모델 아이디와 대조했습니다.
- [ ] 모델 목록을 제공하지 않는 경우 수동 모델을 입력했습니다.
- [ ] 격리 작업 공간에서 새 세션을 만들었습니다.
- [ ] 최소 텍스트 요청이 성공했습니다.
- [ ] 제한된 도구 호출이 성공했습니다.
- [ ] 기존 세션과 새 기본 모델의 동작 차이를 기록했습니다.
- [ ] 검증된 회귀 경로를 남겼습니다.
- [ ] 하니스나 게이트웨이 업그레이드 뒤 재검증 일정과 담당자를 정했습니다.
회사 게이트웨이를 기존 개발 PC에만 붙이면 네트워크 정책, 실행 중인 프로세스의 환경 변수, 세션 재현 환경을 따로 관리해야 하는 부담이 생깁니다. 반대로 격리된 맥 환경은 테스트용 작업 공간을 분리하기 쉽고, 원격 접속으로 같은 조건을 반복 검증하기 좋습니다. 다만 장기간 고정 부하를 처리하거나 물리 장치와 직접 연결해야 한다면 자체 서버나 사내 장비가 더 적합할 수 있습니다. 모델 게이트웨이를 단기간 검증하거나 배포 전 회귀 테스트를 수행하는 목적이라면, 프로젝트별로 되돌릴 수 있는 원격 맥 환경을 NUKCLOUD 원격 맥 안내에서 확인한 뒤 본문의 텍스트와 도구 호출 검증 결과를 기준으로 장기 운영 여부를 결정하는 편이 합리적입니다.