DeepSeek Harness B.AI API 공식 구성 가이드

DeepSeek Harness는 주목받는 오픈 소스 AI 작업 공간 애플리케이션으로, 현재 개발자 미리보기 단계에 있습니다. 이 애플리케이션은 로컬 작업 공간에서 코드 및 파일 분석을 지원할 뿐만 아니라, 개방형 사용자 정의 Provider 메커니즘을 통해 개발자에게 큰 유연성을 제공합니다. B.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 설치 명령을 실행할 수 있습니다.

macOS

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

Node.js 공식 다운로드 페이지에서 사용 중인 Linux 배포판 및 시스템 아키텍처를 선택하고 페이지에서 제공하는 패키지 관리자 명령에 따라 LTS 버전을 설치하십시오. Ubuntu, Debian, Fedora 등 다양한 배포판의 설치 명령이 다르므로, 설치 과정이 안전하고 정확하게 진행되도록 공식 페이지에서 동적으로 생성된 명령을 따르는 것이 좋습니다.

설치가 끝난 후, 현재 열려 있는 모든 터미널 창을 닫고 새로운 터미널을 다시 열어야 합니다(Windows 사용자는 PowerShell을, macOS 사용자는 Terminal을, Linux 사용자는 시스템 터미널을 사용하십시오).

세 시스템 모두에서 다음 동일한 검사 명령을 실행합니다:

세 개의 명령이 모두 버전 번호를 반환하면 환경이 준비된 것입니다.

GitHub 소스 코드를 통해 프로젝트를 구축하고 실행할 계획이라면 Git 환경이 필요합니다. 먼저 터미널에서 git --version을 실행하여 설치 여부를 확인하십시오. 설치되지 않은 경우, 운영 체제에 따라 다음 명령을 실행하십시오:

Windows

macOS

Ubuntu 또는 Debian

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

2. npx로 DeepSeek Harness 시작하기 (추천)

B.AI API를 일반적으로 사용하고 구성하는 개발자에게는 npx로 직접 시작하는 것을 추천합니다.

터미널에서 다음 명령을 실행하십시오(세 시스템 모두에 해당):

처음 실행 시: 시스템에서 필요한 소프트웨어 패키지를 다운로드할 것인지 묻습니다. y를 입력하고 Enter를 눌러 확인하십시오.

시작 과정에서 의존성 폐기 경고가 나타나면 정상적인 현상이며, 개입할 필요가 없습니다.

터미널에서 로컬 주소가 출력되면 DeepSeek Harness의 웹 서비스가 성공적으로 시작된 것입니다.

터미널 창을 열어 두고 브라우저 주소창에 다음을 입력하십시오:

이 주소는 로컬에서만 접근 가능합니다. 터미널 창을 닫거나 창에서 Ctrl+C를 누르면 로컬 서비스가 중지됩니다. 브라우저에서 127.0.0.1:3080을 열 수 없는 경우, 먼저 터미널이 여전히 실행 중인지 확인하고, 터미널 내에서 위의 dsh web 주소가 출력되었는지 확인하십시오. 필요 시, 시작 명령을 다시 실행하십시오.

3. 소스 코드 빌드 방법 (고급)

플러그인을 개발하거나 소스 코드를 수정하거나 프로젝트 개발에 참여할 계획이라면 공식 GitHub 저장소에서 소스 코드를 가져올 수 있습니다.

공식 저장소: https://github.com/deepseek-ai/deepseek-harness

GitHub에서 제공하는 것은 프로젝트 소스 코드이며, 다운로드 후에는 반드시 터미널을 통해 의존성 설치 및 프로젝트 빌드를 완료해야 하며, 파일을 두 번 클릭하여 직접 실행할 수 없습니다. 다음 두 가지 방법으로 소스 코드를 가져오고 실행할 수 있습니다:

방법 1: ZIP 소스 코드 패키지 다운로드 저장소 페이지에서 녹색의 Code 버튼을 클릭하고 Download ZIP을 선택합니다. 다운로드 후 압축을 풀고 터미널을 열어 cd 명령을 사용하여 압축 해제된 프로젝트 디렉토리로 들어가 다음 명령을 차례로 실행합니다:

방법 2: Git으로 클론하기 먼저 git --version을 실행하여 Git 환경이 존재하는지 확인하는 것이 좋습니다. 설치되지 않은 경우, 앞서 설명한 "환경 준비" 부분을 참조하여 해당 시스템의 Git 설치를 완료하십시오. 환경이 올바른지 확인한 후, 터미널을 다시 열고 다음 명령을 실행합니다:

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 인터페이스 정보 입력: 사용자 정의 제공자를 연 후 아래 내용을 입력하십시오.

단계 4, 모델 디렉토리 가져오기 및 Provider 생성 완료: 기본 정보 입력이 완료되면 "모델 디렉토리" 영역으로 스크롤하십시오. 시스템은 두 가지 추가 방법을 제공합니다: "모델 추가"를 클릭하여 모델 ID를 수동으로 입력하거나 오른쪽 상단의 "사용 가능한 모델 가져오기"를 클릭합니다.

추천 작업: 우선 "사용 가능한 모델 가져오기"를 클릭하세요. DeepSeek Harness가 B.AI에 현재 계정에서 사용할 수 있는 모델 디렉토리를 요청합니다. 모델 목록이 정상적으로 반환되면 B.AI API 키, 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라는 이름의 사용자 정의 제공자가 추가되며, 옆에 녹색 원이 표시됩니다. 이는 B.AI 사용자 정의 제공자가 성공적으로 저장되었고 사용 가능한 상태임을 나타냅니다. 주의: 이때 DeepSeek 공식 제공자가 여전히 빨간 점으로 표시된다면, 이는 DeepSeek 공식 API 키를 입력하지 않았기 때문이며, 이는 녹색 점에 해당하는 B.AI 인터페이스의 정상 사용에는 영향을 미치지 않습니다.

단계 5, 링크 연결성 검증: 설정 창을 닫고 메인 화면으로 돌아가 새 세션을 만듭니다. 모델 선택기에서 B.AI 제공자를 선택한 후 방금 추가한 DeepSeek 모델을 선택하여 다음 테스트를 진행합니다:

• 기본 대화 테스트: 모델 선택기에서 B.AI 및 해당 모델을 선택하고 명령을 전송합니다:

정상적으로 내용을 반환하는지, 스트리밍 출력이 있는지 관찰하고 현재 제공자가 B.AI인지, 모델 ID가 선택한 것과 일치하는지 확인합니다.

• 도구 호출 테스트: 읽기 전용 명령을 전송하여 도구 링크를 검증합니다:

명령에서 "파일을 수정하거나 삭제하지 마세요"라고 특별히 강조하는 것은 현재 작업 공간을 변경하지 않고도 Harness의 도구 호출 링크가 원활한지 안전하고 빠르게 검증하기 위함입니다.

위의 두 가지 테스트를 수행하는 동안 DeepSeek Harness를 실행하는 터미널 창을 다시 확인하여 콘솔에 401, 404, model not found 또는 기타 요청 오류 정보가 나타나지 않는지 확인하세요. 터미널이 안정적으로 실행되면 모든 연결 및 검증 작업을 성공적으로 완료한 것입니다.

자주 묻는 질문 Q&A

Q1: 터미널에서 node, npm 또는 npx 명령을 찾을 수 없다고 표시되나요?

이는 일반적으로 Node.js가 아직 설치되지 않았거나 새로 설치된 명령 경로가 현재 터미널에서 읽히지 않기 때문입니다. 모든 터미널 창을 닫고 다시 열어 실행하세요.

여전히 명령을 찾을 수 없다면 Node.js 공식 다운로드 페이지로 돌아가 현재 LTS 버전이 설치되었는지 확인하세요. Windows 사용자는 시스템의 "설치된 응용 프로그램"에서 Node.js를 확인할 수 있으며, macOS 및 Linux 사용자는 which node 명령을 실행하여 명령 경로를 확인할 수 있습니다.

Q2: 시작할 때 npm warn deprecated가 나타나는데 처리해야 하나요?

먼저 아래 주소가 나타나는지 확인하세요:

해당 주소가 정상적으로 표시되면 웹 서비스가 성공적으로 시작된 것입니다. deprecated는 이번 실험에서 의존성 폐기 경고에 해당하며 계속 사용할 수 있습니다. 터미널이 이후 비정상적으로 종료되거나 로컬 주소를 출력하지 않으면 터미널 끝의 구체적인 오류 정보를 바탕으로 문제를 조사하세요.

Q3: 브라우저에서 127.0.0.1:3080을 열 수 없으면 어떻게 하나요?

먼저 dsh web을 실행하는 터미널 창이 여전히 열려 있는지 확인하세요. 해당 터미널을 닫거나 Ctrl+C 단축키를 사용하면 로컬 서비스가 종료됩니다.

서비스가 중지되었다면 시작 명령을 다시 실행하세요:

터미널에서 "포트가 사용 중입니다"라는 메시지가 표시되면 이전에 남아 있는 DeepSeek Harness 프로세스를 종료한 후 다시 시도하세요.

Q4: 모델 호출 시 401 Unauthorized 오류가 발생하면 어떻게 조사하나요?

401 오류는 일반적으로 API 키 인증 실패를 나타냅니다. 다음을 확인하세요:

• API 키가 완전하게 복사되었는지, 앞뒤에 불필요한 공백이 없는지 확인하세요.

• 해당 API 키가 B.AI 콘솔에서 유효(비활성화되지 않음) 상태인지 확인하세요.

• 키가 올바른 구성 항목에 입력되었는지 확인하세요: 첫 번째 팝업의 "DeepSeek 공식 제공자"에 입력하지 말고 "설정 → 모델 → 사용자 정의 제공자 추가"에 해당하는 B.AI 인터페이스에 입력해야 합니다.

Q5: 모델 호출 시 404 Not Found 오류가 발생하면 어디에 잘못 입력된 건가요?

API 주소가 완전하게 입력되었는지 확인하세요.

Q6: model not found 오류가 발생하면 어떻게 해결하나요?

B.AI 사용자 정의 제공자의 편집 페이지로 돌아가 "사용 가능한 모델 가져오기"를 다시 클릭하세요. 선택하거나 입력한 모델 ID가 시스템에서 반환된 결과와 완전히 일치하는지 확인하고 모든 대소문자, 하이픈 및 버전 번호를 엄격하게 유지하세요. 또한 계정 권한 업데이트나 공식 모델 디렉토리 조정으로 인해 이전 모델이 사용할 수 없게 될 수 있으므로 오류가 발생하면 항상 현재 새로 가져온 모델 목록을 기준으로 하세요.

Q7: B.AI 상태가 녹색 점으로 표시되지만 여전히 대화가 불가능한가요?

녹색 점은 구성 정보가 저장되었음을 나타냅니다. 대화가 불가능하다면 현재 세션에서 B.AI 제공자 및 해당 모델이 올바르게 선택되었는지, 모델 ID가 정확한지, 그리고 귀하의 B.AI 계정이 해당 모델 호출 권한 및 사용 가능 한도를 가지고 있는지 확인하세요. 이후 터미널의 마지막 오류 코드(예: 401/404)를 참고하여 문제를 조사하세요.

Q8: Windows, macOS 및 Linux 시스템의 접속 페이지에 차이가 있나요?

세 시스템의 준비 환경은 약간의 차이가 있습니다. dsh web이 시작된 후 모든 시스템은 브라우저를 통해 http://127.0.0.1:3080에 접근하며, B.AI 제공자 추가, 모델 가져오기 및 대화 검증 단계는 기본적으로 일관됩니다.

참고 링크:

• 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/