English Arabic Français Deutsch 日本語 한국어 Português Русский Español

DeepSeek Harness와 Novita AI: 설정 가이드, API 키, 모델 선택

작성자 / / AI 에이전트, LLM / 10 분 읽기
DeepSeek Harness와 Novita AI: 설정 가이드, API 키, 모델 선택
목차
  1. DeepSeek Harness란 무엇인가
  2. 설정 전에 필요한 것
  3. Novita AI 모델을 연결하는 방법
  4. 설정 후 실행할 수 있는 작업
  5. 작업에 적합한 모델을 선택하는 방법
  6. 일반적인 설정 문제 해결
  7. 자주 묻는 질문
  8. 추천 문서
  9. 출처

DeepSeek Harness는 Harness Web UI를 로컬에서 실행하고 Novita AI를 OpenAI 호환 커스텀 모델 공급자로 추가하여 Novita AI와 함께 작동합니다. Node.js를 설치하고 npx @deepseek-ai/dsh web을 실행한 다음 http://127.0.0.1:3080을 열고, 공급자 기본 URL로 https://api.novita.ai/openai를, 자격 증명으로 Novita AI API 키를, Novita AI 모델 라이브러리의 모델 ID를 사용하세요. 설정은 몇 분이면 끝나지만, 실제 작업은 코딩, 리포지토리 분석, 연구, 대량 작업에 적합한 모델을 선택하는 것입니다.

DeepSeek Harness란 무엇인가

DeepSeek Harness는 "모든 것이 플러그인"인 아키텍처를 기반으로 DeepSeek AI가 구축한 오픈소스 에이전트 하네스입니다. 공식 문서에서는 이 프로젝트가 개발자 프리뷰 단계이며 호환성을 깨는 변경이 발생할 가능성이 높다고 설명합니다. 따라서 프로덕션에서 가장 좋은 방법은 작동하는 버전을 고정하고, 변경 사항을 업그레이드 전에 검토하며, 각 업그레이드 후 통합을 검증하는 것입니다.

모델과 하네스의 차이는 실제로 실행해보면 더 쉽게 알 수 있습니다. LLM은 프롬프트를 읽고 다음에 무엇을 할지 결정합니다. 하네스는 그 결정에 실행 경로, 즉 작업 공간, 도구, 셸, 브라우저, 세션, 저장소, 그리고 다음 작업을 선택하기 전에 발생한 일을 관찰하는 방법을 제공합니다. DeepSeek Harness는 이 루프를 사용자 머신에서 실행하는 Web UI로 패키징하며, 추론 모델은 API 서비스로 남을 수 있습니다.

이러한 설계는 여러 작업에 적합합니다:

  • 코드베이스 변경. 에이전트가 파일을 검사하고, 패치를 제안하고, 테스트를 실행하고, 실패 후 수정하도록 합니다.
  • 리포지토리 트라이지. 익숙하지 않은 의존성을 탐색하고, 호출 경로를 매핑하고, 위험 영역을 요약하고, 후속 티켓을 작성합니다.
  • 연구 및 보고서. 여러 페이지에 분산된 답변을 찾을 때 브라우징, 파일 출력, 구조화된 요약을 결합합니다.
  • 운영 실험. 스크립트를 초안 작성하고, 승인을 받아 로컬에서 실행하고, 워크플로를 확장하기 전에 변경된 내용을 기록합니다.

파일 액세스나 로컬 실행 없이 작고 감사 가능한 API 호출만 필요한 경우에는 덜 적합합니다. 에이전트 하네스는 개발 환경이지 단순한 추론 엔드포인트가 아닙니다. 채팅 완성만 필요하다면 직접 Novita AI LLM API를 사용하는 것이 더 간단합니다.

설정 전에 필요한 것

네 가지가 필요합니다:

  1. Node.js가 설치된 머신.
  2. Novita AI 계정.
  3. Novita AI API 키.
  4. 에이전트가 읽고, 적절한 경우 편집할 수 있는 작업 디렉토리.

Node.js가 설치되어 있는지 확인하려면 다음을 실행하세요:

node --version

공식 DeepSeek Harness 리포지토리는 현재 Node.js ^22.19.0 || >=24.0.0을 지원합니다. 명령어가 이전 버전을 출력하거나 실패하면 nodejs.org에서 Node.js를 설치한 후 확인을 다시 실행하세요. 가능하면 시스템 관리자 권한으로 명령어를 실행하지 마세요. npx가 전역 캐시에 쓸 수 없어 실패하면 root 셸을 여는 대신 Node.js/npm 권한을 수정하세요.

설정을 시작하기 전에 전용 프로젝트 폴더를 만들고, 내용이 중요하다면 소스 제어 아래에 두세요. 도구 액세스 권한이 있는 하네스는 매우 유용할 수 있지만, "이 코드를 봐"라는 것과 "프로덕션에 게시해"라는 것은 위험 수준이 다릅니다. 에이전트의 제안된 작업을 검토하고 필요하지 않은 자격 증명에 연결하지 마세요.

Novita AI 모델을 연결하는 방법

1단계: Novita AI API 키 가져오기

Novita AI에 로그인하고, Key Management를 연 다음 새 키를 생성하고 즉시 복사하세요. 콘솔에서 키를 한 번만 표시한다면, 비밀번호 관리자나 팀에서 이미 사용 중인 로컬 시크릿 저장소에 넣으세요. 문서, 스크린샷, 소스 리포지토리, 공유 채팅에 붙여넣지 마세요.

이 가이드에서는 Harness를 실행할 셸에서 환경 변수로 내보냅니다:

export NOVITA_API_KEY="your-key"

이 변수는 설정을 더 쉽게 만들어 줄 뿐입니다. 다음 섹션의 UI 공급자 구성이 Harness가 모델 호출에 사용하는 것입니다.

2단계: DeepSeek Harness Web UI 실행

공식 README는 다음 npm 실행 경로를 제공합니다:

npx @deepseek-ai/dsh web

첫 번째 실행은 패키지와 의존성을 다운로드하므로 이후 실행보다 시간이 더 걸릴 수 있습니다. 그런 다음 DeepSeek Harness는 기본적으로 http://127.0.0.1:3080에서 Web UI를 열고 기본 브라우저에서 실행합니다. SSH로 작업 중이거나 브라우저 실행을 원하지 않는 경우, 공식 README에는 --no-open 플래그가 문서화되어 있습니다:

npx @deepseek-ai/dsh web --no-open

DeepSeek Harness는 pnpm install, pnpm run build, pnpm dsh web을 사용하여 소스에서 실행할 수도 있지만, npm 경로가 작동하는 UI에 가장 빠른 방법이며 이 가이드에서 사용하는 방식입니다.

3단계: Novita AI를 커스텀 공급자로 추가

DeepSeek Harness가 반복됨에 따라 정확한 레이블은 변경될 수 있지만, 현재 Web UI에서의 목표는 동일합니다: 모델/공급자 설정을 열고 커스텀 OpenAI 호환 공급자를 추가하세요.

필드 사용할 값
표시 이름 Novita AI
공급자 ID novita 또는 다른 안정적인 로컬 식별자
기본 URL https://api.novita.ai/openai
API 키 사용자의 Novita AI API 키
모델 카탈로그 원하는 특정 Novita AI 모델 ID를 새로 고치거나 추가

특정 모델의 경로가 아닌 https://api.novita.ai/openai를 사용하세요. 공급자 ID는 안정적으로 유지하세요. 나중에 이름을 바꾸면 기존 세션 설정이 더 이상 존재하지 않는 공급자를 가리킬 수 있습니다. 공급자를 저장한 후 모델 카탈로그를 새로 고치고 세션 선택기에서 모델을 볼 수 있게 만드세요.

선택할 API 프로토콜은 openai-completions입니다. DeepSeek Harness는 이 프로토콜을 OpenAI Chat Completions용으로 문서화하고 있으며, 대신 해당 요청 형태를 사용하는 게이트웨이를 위해 openai-responses 및 anthropic-messages를 제공합니다.

4단계: 모델 및 작업 공간 선택

DeepSeek Harness UI에서 작업 공간을 열고 방금 추가한 Novita AI 모델 중 하나를 선택하세요. UI에 “get models” 액션이 있다면, 기억에서 모델 ID를 입력하는 대신 사용하세요. 모델 ID는 통합 계약입니다: 잘못된 ID는 네트워크 문제, 권한 문제 또는 빈 카탈로그처럼 보일 수 있습니다.

그런 다음 중요한 코드베이스를 사용하기 전에 작은 작업을 실행하세요:

이 작업 공간의 파일을 나열하고, 주요 진입점을 식별하며, 위험도가 낮은 문서 개선 사항 하나를 제안하세요.

에이전트가 작업 공간을 읽고, 모델을 호출하고, 승인하지 않은 작업 전에 중지할 수 있는지 확인하세요. 이 루프가 작동하면 실제 작업으로 넘어가세요.

모델 검색이 목록을 채우지 못하면 모델 ID를 수동으로 추가하세요. DeepSeek Harness는 모든 게이트웨이가 동일한 목록 형식을 반환하는 것은 아니므로 검색을 편의 기능으로 문서화하고 있습니다.

설정 후 실행할 수 있는 작업

DeepSeek Harness는 단순히 후속 질문을 하는 것이 아니라 에이전트 세션을 정의하고 운영할 수 있는 공간을 제공합니다. 몇 가지 실용적인 시작점은 다음과 같습니다:

기존 코드 경로 설명 및 리팩터링

작업 공간을 서비스나 패키지로 지정하고 에이전트에게 하나의 기능을 끝에서 끝까지 추적하도록 요청하세요. 유용한 출력은 단순한 설명이 아닙니다. 변경 계획, 영향을 받을 파일, 추가할 테스트, 리팩터링이 작동했음을 증명할 신호를 포함할 수 있습니다.

들어오는 요청이 데이터베이스 계층에 도달하는 방법을 추적하세요. 번호가 매겨진 흐름을 생성하고, 가능한 실패 지점을 나열하며, 가장 위험도가 높은 두 경로에 대한 테스트를 제안하세요.

편집을 허용하기 전에 계획을 검토하세요. 모델이 암시적 이니셜라이저, 오래된 설정 경로 또는 여전히 프로덕션 호출자가 있는 오래된 API에 의존하는 코드베이스를 통해 일관성 있어 보이는 경로를 선택할 수 있습니다.

마이그레이션 또는 정리 준비

Harness는 “작업 준비” 작업에 유용합니다. 의존성 인벤토리, API 사용 목록, 호환성 체크리스트 또는 단계별 마이그레이션 계획을 요청하세요. 이러한 아티팩트는 대규모 원샷 패치보다 검토하기 쉽고, 마이그레이션이 다른 팀에 영향을 미치는 경우 필요한 판단을 보존합니다.

연구-파일 워크플로 실행

시장 조사나 기술 비교의 경우 에이전트에게 소스를 수집하고, 날짜를 조정하며, 불일치를 기록하고, 초안 보고서를 로컬 파일에 작성하도록 요청하세요. 결과물을 좁게 유지하세요: "URL과 날짜가 포함된 후보 표 생성"은 "이 시장에서 무슨 일이 일어나고 있는지 알려줘"보다 검증하기 쉽습니다.

반복 가능한 로컬 워크플로 구축

프롬프트가 작동하면, Harness 버전이 지원하는 경우 프로젝트 프롬프트나 플러그인으로 저장하세요. 재사용 가능한 프롬프트는 작업 공간, 필수 입력, 출력 형식 및 안전 경계를 명시해야 합니다. 워크플로가 명령어를 실행하거나 파일을 편집할 때 이 마지막 부분이 중요합니다.

작업에 적합한 모델을 선택하는 방법

Novita AI는 DeepSeek 및 기타 모델 제품군을 지원하므로, 질문은 "어떤 공급자에 하나의 모델이 있는가?"가 아니라 "워크플로의 이 단계에서 어떤 모델을 사용해야 하는가?"입니다. Novita AI 모델 라이브러리의 현재 목록을 확인하고, Harness에 저장하기 전에 모델 페이지에서 정확한 모델 ID를 확인하세요. 모델 ID와 제한사항은 카탈로그가 업데이트됨에 따라 변경됩니다.

다음 라우팅 패턴을 시작점으로 사용하세요:

  • DeepSeek V4.1 Flash 는 플래그십 모델의 비용 프로필 없이 코드 분석, 수학 중심 작업 또는 다단계 설명을 위한 강력한 일반 추론이 필요할 때 유용합니다.
  • GLM 5.3 은 현재 작성 시점의 플래그십 GLM 목록이며, GLM 5.3 Flash 는 효율성 중심의 네이티브 멀티모달 옵션입니다. 전체 리포지토리를 하나의 요청에 넣기 전에 컨텍스트 윈도우와 출력 제한을 확인하세요.
  • Qwen3.8 Flash 및 Qwen3.8 Max 는 현재 Qwen3.8 라인업의 효율성 및 플래그십 끝을 다룹니다. 동일한 패치 작업을 기본 모델에 대해 실행하여 출력을 검토하기 쉬운지 확인하세요.
  • Kimi K3 는 Novita 카탈로그에 있는 Moonshot의 현재 플래그십이며, 긴 컨텍스트, 연구 및 도구 중심 워크플로에 적합합니다. 프로덕션에서 의존하기 전에 도구 호출에 대한 정확한 API 동작을 확인하세요.
  • MiniMax M3 는 가장 최신 MiniMax 목록이며 효율적인 대화형 및 멀티모달 입력 작업에 적합한 후보입니다. 하나의 벤치마크 결과가 전이될 것이라고 가정하지 말고, 자체 프롬프트에 대한 지연 시간과 응답 품질을 측정하세요.

프로덕션 에이전트 작업의 경우, 리더보드보다 세 가지 측정 항목이 더 중요합니다:

  1. 작업 성공. 패치가 테스트를 통과하는가? 보고서에 요청된 섹션이 포함되어 있는가? 도구 호출이 의도한 작업을 수행하는가?
  2. 승인된 결과당 비용. 재시도, 낭비된 출력, 잘못된 계획을 검토하는 데 소요된 인간 시간을 계산하세요.
  3. 실패 모드. 모델이 정중하게 거부하는가, 도구 호출을 환각하는가, 아니면 잘못된 작업을 자신 있게 수행하는가? 마지막 경우 더 엄격한 승인 설정이 필요합니다.

매번 공급자를 편집하지 않고 두 모델을 비교하려면, 둘 다 동일한 Novita AI 공급자에 추가하고 정확한 모델 ID를 저장한 다음 동일한 대표 프롬프트 세트를 실행하세요. 그런 다음 채팅 출력뿐만 아니라 최종 아티팩트를 검사하세요.

일반적인 설정 문제 해결

모델 목록이 비어 있음

기본 URL이 정확히 https://api.novita.ai/openai인지, API 키가 최신인지, 계정에 모델에 대한 액세스 권한이 있는지 확인하세요. UI에 새로 고침 액션이 있으면 공급자를 저장한 후 카탈로그를 새로 고치세요. 그런 다음 Harness 외부에서 직접 API 호출로 키를 테스트하세요.

모델 가져오기가 인증 오류를 반환하면 먼저 키를 확인하세요. Harness 검색은 OpenAI 호환 모델-목록 엔드포인트를 호출하며, 일반 완성 호출이 다른 이유로 실패하는 동안 여기서 실패할 수 있습니다.

공급자는 저장되지만 요청이 실패함

모델 ID가 Novita AI 모델 페이지와 일치하는지 확인하세요. 또한 선택한 모델이 하네스가 수행하는 요청 유형을 지원하는지 확인하세요. 텍스트 전용 모델은 이미지 요청을 지원하지 않을 수 있으며, 도구 지원이 없는 모델은 도구 호출을 기대하는 에이전트 단계에서 실패할 수 있습니다.

npx가 첫 번째 실행에서 중단되거나 실패함

첫 번째 실행은 의존성을 다운로드하므로 시간이 걸릴 수 있습니다. 실패하면 네트워크, npm 캐시 및 Node.js 버전을 확인하세요. 깨끗한 재시도는 합리적입니다. 오류가 권한을 언급하면, 명령어를 상승된 권한으로 실행하는 것보다 사용자 수준의 Node.js 설치 또는 패키지 관리자 캐시를 선호하세요.

브라우저가 열리지 않음

서버가 계속 실행 중일 수 있습니다. 수동으로 http://127.0.0.1:3080을 열거나, npx @deepseek-ai/dsh web --no-open으로 다시 시작하고 동일한 머신의 브라우저에서 URL을 방문하세요. SSH를 통해 전달된 호스트는 127.0.0.1이 아닐 수 있으므로 명령어가 출력한 주소를 사용하세요.

에이전트가 예상치 못한 변경을 수행함

실행을 중지하고, 버전 관리 diff를 검사하며, 원하지 않는 것을 되돌리세요. 그런 다음 도구 범위를 줄이거나 일회용 작업 공간에서 작업을 실행하세요. 팀에서 보호된 브랜치와 배포 자격 증명을 사용하는 경우, 워크플로를 신뢰할 수 있을 때까지 에이전트의 접근 범위 밖에 두세요.

자주 묻는 질문

DeepSeek Harness가 Novita AI 모델을 지원하나요?

DeepSeek Harness는 커스텀 OpenAI 호환 공급자를 지원하며, Novita AI는 OpenAI 호환 API를 제공합니다. 이 가이드는 커스텀 공급자 경로를 사용합니다: 기본 URL로 https://api.novita.ai/openai, Novita AI API 키, Novita AI 모델 페이지의 정확한 모델 ID.

자체 모델 서버를 배포해야 하나요?

아니요. Novita AI가 모델 API를 호스팅하고, DeepSeek Harness가 로컬에서 실행되어 해당 API를 호출합니다. 이 설정을 위해 GPU를 관리할 필요가 없습니다. Node.js 프로세스와 에이전트가 실행하는 모든 도구에 충분한 로컬 리소스는 여전히 필요합니다.

DeepSeek Harness는 프로덕션에 사용할 수 있나요?

공식 리포지토리는 DeepSeek Harness를 개발자 프리뷰로 설명하고 호환성을 깨는 변경에 대해 경고합니다. 오늘날 유용하게 사용할 수 있지만, 버전을 고정하고, 릴리스 노트를 검토하며, 중요한 작업을 소스 제어 아래에 두고, 프로덕션 워크플로를 변경하기 전에 중요하지 않은 작업 공간에서 업그레이드를 테스트하세요.

동일한 프로젝트에서 두 개 이상의 모델을 사용할 수 있나요?

네, UI가 세션에서 모델 전환을 지원한다면 가능합니다. 유용한 패턴은 초안 작성이나 첫 번째 코드 패스에 하나, 검토나 심층 분석에 다른 하나, 그리고 요약, 분류 또는 반복 추출에 저비용 모델을 사용하는 것입니다.

Novita AI API 키는 어디에 저장해야 하나요?

필요할 때만 공급자 구성에 넣고, 그 외에는 로컬 시크릿 관리자나 암호화된 환경 저장소에 보관하세요. 절대 커밋하지 말고, 스크린샷으로 공유하지 말며, 작업에 필요한 것보다 더 넓은 권한을 부여하지 마세요.

실제 코드베이스를 연결하기 전에 무엇을 해야 하나요?

작업 공간을 버전 관리 아래에 두고, 에이전트의 승인 설정을 확인하며, 필요하지 않은 자격 증명을 제거하세요. 읽기 전용 또는 위험도가 낮은 작업부터 시작한 다음, 에이전트가 프로젝트에서 어떻게 동작하는지 이해한 후 도구 세트를 확장하세요.

추천 문서

출처

관련 게시글