
DeepSeek Harness B.AI API 연동 공식 설정 가이드

DeepSeek Harness는 각광받는 오픈 소스 AI 워크스페이스 애플리케이션으로, 현재 개발자 미리보기 단계에 있습니다. 로컬 워크스페이스를 심층적으로 탐색해 코드와 파일 분석을 지원하는 것은 물론, 개방형 커스텀 Provider 기능을 통해 개발자에게 뛰어난 유연성을 제공합니다. 한편 B.AI는 선도적인 AI 인프라로서 고가용성과 저지연을 통합한 풀스택 대형 언어 모델 플랫폼 서비스를 구축했으며, 개발자와 기업에게 강력하고 안정적이며 탄력적인 지능형 연산 네트워크를 제공하고자 합니다.
본 가이드에서는 Windows, macOS, Linux 환경에서 DeepSeek Harness를 처음부터 시작하여 B.AI API와 성공적으로 통합하는 방법을 상세히 안내합니다. 본 튜토리얼을 따라 진행하시면 로컬 워크스페이스부터 대형 모델까지 전주기 호출 체인을 완성할 수 있으며, AI 기반 생산성 및 혁신 잠재력을 최대한 발휘하게 됩니다.
최종 구현 호출 경로: DeepSeek Harness → B.AI API → B.AI 제공 모델
1. 환경 준비
DeepSeek Harness는 Node.js에 포함된 npx 명령어로 실행됩니다. 시스템에 최신 사용 가능한 Node.js LTS 버전이 설치되어 있는지 확인하세요.
공식 다운로드 주소: https://nodejs.org/en/download
Windows
.msi 인스톨러를 직접 다운로드하거나, 시작 메뉴에서 PowerShell을 검색하여 실행한 후 WinGet 설치 명령어를 실행할 수 있습니다.
winget --versionwinget install --id OpenJS.NodeJS.LTS -e --source winget
macOS
Node.js 공식 다운로드 페이지에서 macOS Installer를 선택하여 .pkg 파일을 다운로드하고 표시되는 지침에 따라 설치를 완료하세요. 설치 완료 후 Command + Space 키를 눌러 Spotlight 검색을 열고, Terminal을 입력하여 터미널을 실행하세요.
Linux
Node.js 공식 다운로드 페이지에서 사용 중인 Linux 배포판과 시스템 아키텍처를 선택한 뒤, 페이지에서 제공하는 패키지 관리자 명령어를 사용하여 LTS 버전을 설치하세요. Ubuntu, Debian, Fedora 등 배포판마다 설치 명령어가 다르므로, 공식 페이지에서 동적으로 생성된 명령어를 기준으로 하여 안정적인 설치가 이루어지도록 하십시오.
설치 완료 후 현재 열려 있는 모든 터미널 창을 닫고 새 터미널 창을 다시 실행하세요(Windows 사용자: PowerShell, macOS 사용자: Terminal, Linux 사용자: 시스템 기본 터미널).
세 운영체제 모두 다음 동일한 검사 명령어를 실행하세요:
node -vnpm -vnpx -v
세 명령어 모두 버전 번호를 반환하면 환경 준비가 완료된 것입니다.
Node.js v24.19.0npm 11.17.0npx 11.17.0
Github 소스코드로 빌드 및 실행하려는 경우 Git 환경이 필요합니다. 먼저 터미널에서 `git --version` 명령어를 실행하여 설치 여부를 확인하세요. 미설치 시 사용 중인 OS에 따라 다음 명령어를 실행하십시오:
Windows
winget install --id Git.Git -e --source winget
macOS
xcode-select --install
Ubuntu 또는 Debian
sudo apt updatesudo apt install git
참고: npx 방식으로 빠르게 체험하고 B.AI 설정만 예정이라면 Git은 건너뛰어도 무방합니다.
2. npx로 DeepSeek Harness 실행하기 (권장)
일반 사용 및 B.AI API 설정이 필요한 개발자에게는 npx를 직접 사용하여 실행하는 것을 권장합니다.
터미널에서 다음 명령어를 실행하세요(3개 운영체제 공통):
npx @deepseek-ai/dsh web
첫 실행 안내: 시스템에서 필요 패키지를 다운로드할지 여부를 묻습니다. y를 입력하고 Enter 키를 누르세요.
Need to install the following packages@deepseek-ai/[email protected] to proceed? (y)
실행 중 의존성 비권장(deprecated) 경고가 표시되더라도 정상 현상이므로 개입하지 않아도 됩니다.
npm warn deprecated [email protected]
터미널에 로컬 주소를 출력하면 DeepSeek Harness의 Web 서비스가 성공적으로 시작되었음을 의미합니다.
dsh web: http://127.0.0.1:3080
터미널 창은 켜둔 상태로 유지한 후 브라우저 주소창에 다음을 입력하세요:
http://127.0.0.1:3080
해당 주소는 로컬 환경 접속 전용입니다. 터미널 창을 닫거나 Ctrl+C를 누르면 로컬 서비스도 함께 중지됩니다. 브라우저에서 127.0.0.1:3080이 열리지 않을 경우, 먼저 터미널이 계속 실행 중인지 확인하고 터미널 내부에 앞서 언급한 dsh web 주소가 출력되었는지 확인하세요. 필요시 실행 명령어를 다시 실행하십시오.
npx @deepseek-ai/dsh web
3. 소스 코드 빌드 방식 (고급)
플러그인 개발, 소스 수정 또는 프로젝트 참여를 계획 중이라면 공식 Github 저장소에서 소스 코드를 가져올 수도 있습니다.
공식 저장소: https://github.com/deepseek-ai/deepseek-harness
참고로 Github가 제공하는 것은 프로젝트 소스 코드이므로, 다운로드 후 터미널을 통해 의존성 설치 및 프로젝트 빌드를 완료해야 하며, 파일을 더블클릭하여 직접 실행할 수 없습니다. 다음 두 가지 방법으로 소스 코드를 가져와 실행할 수 있습니다:
방법 1: ZIP 소스 코드 다운로드 저장소 페이지에서 초록색 Code 버튼을 클릭한 후 Download ZIP을 선택하세요. 다운로드 및 압축 해제 후 터미널을 실행하고 cd 명령어로 압축 해제된 프로젝트 디렉토리로 이동한 뒤, 다음 명령어를 순서대로 실행하세요:
npm install -g pnpmpnpm installpnpm run buildpnpm dsh web
방법 2: Git Clone 이용 먼저 `git --version` 명령어를 실행하여 Git 환경 존재 여부를 확인하는 것을 권장합니다. 미설치 시 앞서 설명한 '환경 준비' 항목을 참조하여 해당 OS에 맞게 Git을 설치하세요. 환경 확인 후 터미널을 다시 열고 다음 명령어를 실행하세요:
git clone https://github.com/deepseek-ai/deepseek-harness.gitcd deepseek-harnessnpm install -g pnpmpnpm installpnpm run buildpnpm dsh web
ZIP 또는 Git 방식 중 무엇을 사용하든 빌드 및 시작이 성공하면 접근 주소는 동일하게 http://127.0.0.1:3080.
4. B.AI 커스텀 Provider 설정
단계 1: 공식 기본 설정 건너뛰기
DeepSeek Harness에 최초 진입 시 시스템에서 공식 모델의 API Key 입력 창이 표시됩니다. 반드시 '나중에 설정'을 클릭하세요. 여기에 B.AI Key를 입력하면 시스템이 올바르게 인식하지 못합니다.
단계 2: 커스텀 설정 페이지 진입
페이지 좌측 하단의 '설정'을 클릭한 후 좌측 메뉴에서 '모델'을 선택하고 우측의 '커스텀 공급자 추가'를 클릭하세요. 참고: 이때 공식 Provider 옆에 빨간 점이 표시되는 것은 정상 상태이므로 이후 작업에 영향을 주지 않습니다.


단계 3: B.AI 인터페이스 정보 작성
커스텀 공급자 화면을 연 후 아래 내용을 바탕으로 작성하세요.
Provider ID bai표시 이름 B.API 주소 https://api.b.ai/v1API 프로토콜 openai-completionsAPI 키 B.AI 백엔드에서 생성한 유효한 API Key
단계 4: 모델 목록 가져오기 및 Provider 생성 완료
기본 정보 작성이 완료되면 하단에 있는 '모델 목록' 영역으로 스크롤 내리세요. 시스템에서는 두 가지 추가 방식을 제공합니다: '모델 추가'를 클릭하여 모델 ID를 수동으로 작성하거나, 우측 상단의 '사용 가능한 모델 가져오기'를 선택하는 방법입니다.

권장 작업: 우선 '사용 가능한 모델 가져오기'를 클릭하세요. DeepSeek Harness에서 현재 계정의 사용 가능 모델 목록을 B.AI에 직접 요청하게 합니다. 모델 목록이 정상적으로 반환되면 B.AI API Key, https://api.b.ai/v1, openai-completions 프로토콜 및 모델 목록 API 구성이 성공적으로 연결되었음을 증명합니다.
모델 선택 및 추가 주의사항:
- 반환된 목록에서 B.AI에서 현재 이용 가능한 DeepSeek 모델을 체크합니다(예: deepseek-v4-flash 또는 deepseek-v4-pro). 참고: 실제 사용 가능한 모델은 계정 권한과 시기에 따라 동적으로 변동될 수 있으니 실제 반환 결과를 기준으로 하시기 바랍니다.
- 모델 ID 수정 금지: 모델 ID는 B.AI에서 실제로 반환한 목록과 완전히 일치해야 합니다. 대소문자, 하이픈, 버전 번호를 임의로 변경하면 이후 호출 시 `model not found` 오류가 발생할 수 있습니다.
모델 추가가 정확함을 확인하면 폼 하단으로 스크롤하여 '공급자 생성'을 클릭하세요.

생성에 성공하면 설정 페이지에 B.AI라는 이름의 커스텀 Provider가 새로 추가되며, 옆에 녹색 점이 표시됩니다. 이는 B.AI 커스텀 Provider가 성공적으로 저장되어 사용 가능 상태임을 의미합니다. 참고: 이때 DeepSeek 공식 Provider에 여전히 빨간 점이 표시되는 것은 DeepSeek 공식 API Key를 입력하지 않아서이므로, 녹색 점이 표시된 B.AI 인터페이스 정상 사용에는 영향이 없습니다.

단계 5: 호출 경로 연결성 검증
설정 창을 닫고 메인 화면으로 돌아가 새 대화를 작성하세요. 모델 선택기에서 B.AI Provider를 선택한 후 방금 추가한 DeepSeek 모델을 선택하여 다음 테스트를 진행하세요:
기본 대화 테스트: 모델 선택기에서 B.AI 및 대응 모델을 선택한 후 다음 명령어를 전송하세요:
자신을 소개하고 현재 사용하고 있는 모델을 말씀해주세요.
정상적으로 내용을 반환하는지, 스트리밍 출력이 되는지 관찰하고, 현재 Provider가 B.AI이며 모델 ID도 내가 선택한 것과 일치하는지 확인하세요.
도구 호출 테스트: 읽기 전용 명령어를 전송하여 도구 호출 경로를 검증하세요:
현재 작업 공정의 파일을 검토하고 디렉토리 구조를 요약해주세요. 어떠한 파일도 수정하거나 삭제하지 마십시오.
명령구에 '수정이나 삭제를 하지 말라'고 특별히 강조한 것은 현재 작업 공간을 변경하지 않은 채로 Harness의 도구 호출 경로가 원활하게 작동하는지 안전하고 신속하게 검증하기 위함입니다.
위 두 가지 테스트를 수행할 때는 DeepSeek Harness가 실행 중인 터미널 창을 다시 확인하여 콘솔에 401, 404, model not found 또는 기타 요청 오류 메시지가 표시되지 않았는지 확인하세요. 터미널이 안정적으로 실행된다면 이에 따라 모든 연결 및 검증 작업을 성공적으로 완료한 것입니다.
자주 묻는 질문 Q&A
Q1: 터미널에서 node, npm 또는 npx 명령어를 찾을 수 없다는 경고가 표시됩니다?
A: 주로 Node.js 설치가 완료되지 않았거나, 새로 설치된 명령어 경로가 현재 터미널에 로드되지 않았기 때문입니다. 모든 터미널 창을 닫고 다시 실행한 후 재시행하세요.
node -vnpm -vnpx -v
여전히 명령어를 찾을 수 없다면 Node.js 공식 다운로드 페이지로 돌아가 최신 LTS 버전이 설치되었는지 확인하세요. Windows 사용자는 시스템의 '앱' 설정에서 Node.js를 확인할 수 있으며, macOS 및 Linux 사용자는 which node 명령어를 실행하여 명령어 경로를 확인할 수 있습니다.
Q2: 실행 시 npm warn deprecated 경고가 나타나는데 처리해야 하나요?
우선 뒤에 다음 주소가 나타나는지 확인하십시오:
dsh web: http://127.0.0.1:3080
해당 주소가 정상적으로 표시된다면 Web 서비스가 성공적으로 시작되었음을 의미합니다. 이번 테스트 과정에서 나타난 deprecated 경고는 의존성 비권장 사항이므로 계속 사용해도 무방합니다. 터미널이 이후 비정상 종료되거나 로컬 주소를 출력하지 않는다면 터미널 하단의 구체적 오류 메시지를 기반으로 추가 진단하십시오.
Q3: 브라우저에서 127.0.0.1:3080을 열 수 없습니다. 어떻게 해야 하나요?
A: 먼저 dsh web를 실행 중인 터미널 창이 아직 켜져 있는지 확인하세요. 해당 터미널을 닫거나 Ctrl+C 단축키를 누르면 로컬 서비스가 종료됩니다.
서비스가 중지되었다면 다음 실행 명령어를 다시 실행하십시오:
npx @deepseek-ai/dsh web
터미널에서 '포트가 이미 사용 중'이라는 알림이 표시되면: 이전에 남아있던 DeepSeek Harness 프로세스를 먼저 종료한 후 재시도하십시오.
Q4: 모델 호출 시 401 Unauthorized 오류가 발생했는데 어떻게 진단해야 하나요?
A: 401 오류는 일반적으로 API Key 인증 실패를 의미합니다. 다음을 확인하십시오:
- API Key가 완전하게 복사되었는지, 앞뒤로 불필요한 공백이 없는지 확인하세요.
- 해당 API Key가 B.AI 제어 패널에서 유효(비활성화되지 않음) 상태인지 확인하세요.
- Key가 올바른 설정 항목에 입력되었는지 확인하세요: 첫 번째 팝업 창의 'DeepSeek 공식 Provider'에 입력해서는 안 되며, 반드시 '설정 → 모델 → 커스텀 공급자 추가'에 해당하는 B.AI 인터페이스 안에 입력해야 합니다.
Q5: 모델 호출 시 404 Not Found 오류가 발생했는데, 어디가 잘못 입력되었나요?
A: API 주소가 완전하게 작성되었는지 확인하십시오.
https://api.b.ai/v1
Q6: model not found 메시지가 표시되면 어떻게 해결해야 하나요?
A: B.AI 커스텀 Provider 편집 페이지로 돌아간 후 '사용 가능한 모델 가져오기'를 다시 클릭하십시오. 선택하거나 입력한 모델 ID가 시스템에서 반환한 결과와 완전히 일치하는지 확인하고, 모든 대소문자, 하이픈, 버전 번호를 엄격히 그대로 유지하십시오. 또한 계정 권한 업데이트나 공식 모델 목록 조정으로 인해 기존 모델이 사용 불가해질 수 있으므로, 오류 발생 시 항상 현재 새로 가져온 모델 목록을 기준으로 하시기 바랍니다.
Q7: B.AI 상태에 녹색 점이 표시되어 있으나 여전히 대화가 불가능합니다?
A: 녹색 점은 설정 정보가 저장되었음을 의미할 뿐입니다. 대화가 불가능하다면 현재 세션에서 B.AI Provider 및 해당 특정 모델이 정확하게 선택되었는지, 모델 ID에 오류가 없는지 확인하고, B.AI 계정에 해당 모델 호출 권한 및 잔여 요금이 있는지 확인하십시오. 그 후 터미널 하단의 마지막 오류 코드(예: 401/404)를 바탕으로 표적 진단을 진행하십시오.
Q8: Windows, macOS, Linux 시스템 간 접속 페이지에 차이가 있나요?
A: 세 운영체제의 환경 준비 과정에는 약간의 차이가 있습니다. dsh web를 실행한 후에는 모든 시스템에서 브라우저를 통해 http://127.0.0.1:3080에 접속하며, B.AI Provider 추가, 모델 가져오기, 대화 검증 단계는 기본적으로 동일합니다.
참고 링크:
- Node.js 공식 다운로드 페이지:https://nodejs.org/en/download
- DeepSeek Harness 공식 저장소:https://github.com/deepseek-ai/deepseek-harness
- B.AI API 문서:https://docs.b.ai/llmservice/api/















