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 --version
winget install --id OpenJS.NodeJS.LTS -e --source winget

• macOS

Node.js 공식 다운로드 페이지에서 macOS Installer를 선택하고 .pkg 파일을 다운로드하여 안내에 따라 설치를 완료합니다. 설치가 끝나면 Command + Space를 눌러 스포트라이트 검색을 열고 Terminal을 입력하여 터미널로 들어갑니다.

• Linux 

Node.js 공식 다운로드 페이지에서 사용 중인 Linux 배포판과 시스템 아키텍처를 선택하고, 페이지에 제공된 패키지 관리자 명령을 사용하여 LTS 버전을 설치하세요. Ubuntu, Debian, Fedora 등 배포판마다 설치 명령이 다르므로, 공식 페이지에서 동적으로 생성된 명령을 따르는 것이 안정적인 설치를 보장하는 가장 좋은 방법입니다.

설치가 끝나면 현재 열려 있는 모든 터미널 창을 닫고 새 터미널을 다시 엽니다 (Windows 사용자는 PowerShell, macOS 사용자는 Terminal, Linux 사용자는 시스템 터미널을 사용하세요).

세 시스템 모두에서 동일한 확인 명령 세트를 실행합니다:

node -v
npm -v
npx -v

세 명령 모두 버전 번호가 반환되면 환경 준비가 완료된 것입니다.

Node.js v24.19.0
npm 11.17.0
npx 11.17.0

GitHub 소스 코드를 통해 프로젝트를 빌드하고 실행하려면 Git 환경이 필요합니다. 먼저 터미널에서 git --version을 실행하여 설치 여부를 확인하세요. 설치되어 있지 않다면 운영 체제에 따라 다음 명령을 실행하세요:

Windows 

winget install --id Git.Git -e --source winget

macOS 

xcode-select --install

Ubuntu 또는 Debian 

sudo apt update
sudo apt install git

참고: npx 방식을 사용하여 빠르게 체험하고 B.AI를 구성할 계획이라면 Git 설치는 건너뛰어도 됩니다.

2.  npx를 사용하여 DeepSeek Harness 시작하기 (권장)

일반적인 사용 및 B.AI API 구성에는 npx를 사용하여 직접 시작하는 것을 권장합니다.

터미널에서 다음 명령을 실행하세요 (세 운영 체제 공통):

npx @deepseek-ai/dsh web

첫 실행 시 안내: 시스템에서 필요한 패키지를 다운로드할지 묻습니다. y를 입력하고 Enter를 눌러 확인하세요.

Need to install the following packages
@deepseek-ai/dsh@...
Ok to proceed? (y)

시작 과정에서 종속성 폐기(deprecated) 경고가 나타나면 정상적인 현상이므로 걱정하지 않아도 됩니다.

npm warn deprecated node-domexception@1.0.0

터미널에 로컬 주소가 출력되면 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 pnpm
pnpm install
pnpm run build
pnpm dsh web

방법 2: Git 클론 사용 먼저 git --version을 실행하여 Git 환경이 있는지 확인하는 것이 좋습니다. 설치되어 있지 않다면 앞선 '환경 준비' 섹션을 참조하여 해당 시스템에 Git을 설치하세요. 환경이 제대로 준비되었는지 확인한 후 터미널을 다시 열고 다음 명령을 실행합니다:

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
npm install -g pnpm
pnpm install
pnpm run build
pnpm 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.AI
API 주소 https://api.b.ai/v1
API 프로토콜 openai-completions
API 키 B.AI 콘솔에서 생성한 유효한 API Key

4단계: 모델 카탈로그 가져오기 및 Provider 생성 완료

기본 정보 입력이 끝나면 '모델 카탈로그' 영역까지 아래로 스크롤하세요. 시스템은 두 가지 추가 방법을 제공합니다: '모델 추가'를 클릭하여 모델 ID를 수동으로 입력하거나, 오른쪽 상단의 '사용 가능한 모델 가져오기'를 클릭합니다.

권장 작업: 우선 '사용 가능한 모델 가져오기'를 클릭하세요. DeepSeek Harness가 B.AI에 직접 요청하여 현재 계정에서 사용 가능한 모델 카탈로그를 가져옵니다. 모델 목록이 정상적으로 반환되면 B.AI API Key, https://api.b.ai/v1, openai-completions 프로토콜, 그리고 모델 카탈로그 인터페이스 등의 구성이 성공적으로 연결되었음을 의미합니다.

모델 선택 및 추가 시 주의사항:

• 반환된 목록에서 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가 아직 설치되지 않았거나, 새로 설치된 명령 경로가 현재 터미널에서 아직 인식되지 않았기 때문입니다. 모든