공식 전제 조건부터 확인하는 배포 순서
공식 튜토리얼은 파이썬 3.10 이상, 깃, 맥 운영체제 14 이상과 애플 실리콘 환경, 그리고 모델 엔드포인트와 인증 정보를 요구합니다. 따라서 딥시크 하네스 파이썬 SDK 배포는 로컬 프로젝트를 통째로 복사하는 방식이 아니라, 격리 작업 공간에서 단일 작업을 검증한 뒤 버전과 세션을 고정하는 방식으로 진행해야 합니다. (github.com)
이 글은 다음 독자를 위한 실행용 문서입니다.
- 파이썬으로 딥시크 하네스 코드 작업을 자동화하려는 개발자
- 클라우드 맥에서 SDK 세션을 계속 실행하려는 플랫폼 엔지니어
- 외부에서 전달받은 맥 환경의 재시작과 복구 가능성을 검수해야 하는 프로젝트 책임자
1단계: 작업 유형과 책임 범위를 먼저 고정합니다
처음에 정해야 하는 것은 설치 명령이 아니라 작업의 수명입니다. 일회성 스크립트인지, 정해진 시간에 실행되는 작업인지, 장시간 살아 있는 에이전트인지에 따라 작업 공간과 세션 보존 정책이 달라집니다.
실무에서 자주 생기는 문제는 다음과 같습니다.
- 현재 작업 폴더와 에이전트가 수정할 폴더가 달라 파일 변경 위치가 어긋납니다.
- 대화 기록과 셸 상태를 같은 폴더에 섞어 백업하면 복구 시 어떤 파일이 실행 대상인지 구분하기 어렵습니다.
- 인증 키를 실행 파일이나 저장소에 넣으면 로그, 압축 파일, 오류 보고서로 유출될 수 있습니다.
- SDK가 런타임을 시작해도 중단, 시간 초과, 재시작, 로그 순환을 대신 책임지는 것은 아닙니다.
- 개발자 미리 보기 단계에서는 패키지와 설정 형식이 바뀔 수 있으므로 버전 고정 없는 장기 운영이 위험합니다.
주의: 공식 예제 구성은 지속 셸과 파일 도구를 사용하며 런타임 프로세스가 접근할 수 있는 경로를 수정할 수 있습니다. 처음에는 반드시 폐기 가능한 저장소로 실행해야 합니다. ([github.com](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/user/guide/python-sdk.md))
2단계: 파이썬 환경과 번들 런타임을 분리해 설치합니다
공식 파이썬 SDK는 deepseek-harness-sdk 배포판과 같은 버전의 deepseek-harness-runtime-bin 런타임을 함께 설치하는 구조입니다. 설치된 런타임은 대상 맥에 시스템용 노드 설치를 요구하지 않습니다. 반면 저장소에서 직접 런타임을 빌드하는 개발자 흐름은 별도의 빌드 조건이므로, 배포 환경에 소스 빌드 요구 사항을 그대로 적용하면 안 됩니다. (github.com)
| 항목 | 배포 환경에서 확인할 값 | 편집 평가 |
|---|---|---|
| 운영체제 | 맥 운영체제 14 이상, 애플 실리콘 | 5점 |
| 파이썬 | 3.10 이상 | 5점 |
| 런타임 | SDK와 같은 버전의 번들 런타임 | 5점 |
| 노드 설치 | 번들 실행 파일 방식이면 불필요 | 4점 |
| 소스 빌드 | 개발 및 검증 목적에 한정 | 2점 |
python3 -m venv .venv
. .venv/bin/activate
python -m pip install deepseek-harness-sdk설치 직후에는 다음 정보를 기록합니다.
- 맥 운영체제 버전
- 프로세서 구조
- 파이썬 버전
deepseek-harness-sdk버전deepseek-harness-runtime-bin버전- 설치 시각과 패키지 출처
- 가상 환경 경로
close()가 호출될 때 종료하는 흐름을 제공합니다. ([github.com](https://github.com/deepseek-ai/deepseek-harness/blob/master/python/sdk/README.md))
3단계: 모델, 작업 공간, 도구를 한 번에 검증합니다
첫 작업은 기능을 많이 보여주는 작업이 아니라 실패 지점을 분리하는 작업이어야 합니다. 폐기 가능한 저장소에 작은 텍스트 파일 하나를 만들고, 다음 세 가지를 따로 확인합니다.
- 모델 응답이 반환되는지 확인합니다.
- 파일 읽기와 쓰기가 지정한 작업 공간 안에서 발생하는지 확인합니다.
- 셸 실행 결과와 종료 상태가 기록되는지 확인합니다.
| 검증 단계 | 성공 신호 | 실패 시 되돌릴 위치 |
|---|---|---|
| 모델 호출 | 최종 응답과 종료 상태가 반환됨 | 모델 주소와 인증 변수만 남긴 최소 호출 |
| 파일 작업 | 지정 작업 공간 안에 예상 파일만 생성됨 | 빈 작업 공간으로 재실행 |
| 셸 작업 | 명령 결과와 오류 상태가 세션 기록에 남음 | 셸 도구를 제외한 최소 구성 |
| 기록 저장 | 세션 루트에 새 기록이 생김 | 세션 루트 권한과 절대 경로 확인 |
| 종료 | 문맥 종료 뒤 런타임 프로세스가 남지 않음 | 수동 종료와 프로세스 목록 확인 |
DEEPSEEK_BASE_URL, 인증 정보는 DEEPSEEK_API_KEY처럼 환경 변수로 주입합니다. 프록시를 사용할 경우 기본 엔드포인트를 그대로 가정하지 말고, 먼저 단일 요청으로 연결을 확인합니다. 공식 문서는 번들 런타임이 이 환경 변수를 상속한다고 설명합니다. ([github.com](https://github.com/deepseek-ai/deepseek-harness/blob/master/python/sdk/README.md))
4단계: 작업 공간과 세션 루트를 서로 다른 책임으로 둡니다
파이썬 SDK의 session_root는 어디에 두어야 합니까?
작업 저장소 안이 아니라, 별도의 영속 데이터 경로에 두는 것이 좋습니다. 예를 들면 작업 공간은 /srv/agent/workspace 계열, 세션 루트는 /srv/agent/sessions 계열로 분리합니다. 핵심은 두 경로가 모두 절대 경로이고, 실행 계정에 필요한 읽기·쓰기 권한이 있으며, 백업 정책에서 서로 다른 대상으로 식별되는 것입니다.
공식 안내에서 cwd는 에이전트가 사용할 작업 공간을 정하고, session_root는 세션 기록과 상태를 저장하는 경로로 설명됩니다. 같은 세션 식별자를 재사용하면 대화뿐 아니라 세션이 소유한 셸 프로세스의 현재 위치, 내보낸 변수, 셸 함수까지 이어질 수 있습니다. (github.com)
같은 세션 식별자를 다른 프로세스에서도 이어서 사용할 수 있습니까? 기술적으로는 같은 세션 기록을 읽을 수 있는 조건을 만들 수 있지만, 운영에서는 먼저 동시 접근을 금지해야 합니다. 이전 프로세스가 아직 살아 있거나 같은 세션에 두 작업이 동시에 들어가면 메시지 순서와 셸 상태의 소유권이 불명확해집니다. 연속 작업만 기존 식별자를 재사용하고, 독립 작업은 새 식별자를 발급하십시오.
권장 규칙은 다음과 같습니다.
- 새 프로젝트 또는 새 업무는 새 세션 식별자를 사용합니다.
- 같은 프로젝트의 다음 단계만 기존 식별자를 재사용합니다.
- 프로세스 교체 전에는 이전 실행이 종료됐는지 확인합니다.
- 세션 루트 백업에는 기록 파일과 상태 파일을 함께 포함합니다.
- 작업 공간 백업과 세션 백업을 하나의 복구 단위로 취급하지 않습니다.
5단계: 지속 실행 전에 자격 증명과 프로세스 소유자를 정합니다
지속 실행으로 전환하면 SDK 설치보다 프로세스 책임이 더 중요해집니다. 누가 시작하는지, 누가 중단하는지, 어떤 조건에서 시간 초과로 판단하는지, 로그를 얼마나 보관하는지, 맥 재시작 뒤 누가 복구하는지를 문서로 남겨야 합니다.
인증 정보는 다음 우선순위로 관리합니다.
- 실행 계정의 환경 변수
- 접근 권한이 제한된 별도 자격 증명 파일
- 외부 비밀 저장소에서 실행 시점에 주입하는 방식
맥 운영체제 재시작 뒤 SDK 세션은 어떻게 복구합니까?
SDK 자체가 자동 재시작이나 완성된 데몬 기능을 제공한다고 가정하지 마십시오. 재시작 복구는 별도의 실행 관리자가 담당해야 합니다. 복구 순서는 프로세스 중복 여부 확인 → 작업 공간 경로 확인 → 세션 기록 읽기 → 마지막 완료 상태 확인 → 미완료 작업 재실행 여부 결정으로 고정합니다.
특히 마지막 작업이 이미 모델 요청을 보냈는지 알 수 없다면 자동 재실행을 금지하고 사람의 확인을 받는 편이 안전합니다. 네트워크가 끊긴 뒤 응답만 유실됐을 수 있기 때문입니다.
경험상 가장 위험한 복구는 “세션 파일이 있으니 마지막 요청을 다시 보낸다”는 규칙입니다. 요청의 외부 효과가 파일 변경이나 배포라면, 먼저 실제 변경 상태를 확인하고 중복 실행 가능성을 기록해야 합니다.
6단계: 재시작과 회귀 검증을 통과한 뒤 운영 범위를 넓힙니다
정식 배포 전에는 정상 실행만 확인해서는 부족합니다. 다음 체크리스트를 실제 클라우드 맥에서 순서대로 실행하십시오.
- [ ] 가상 환경을 새 셸에서 다시 활성화하고 SDK와 런타임 버전을 기록합니다.
- [ ] 작업 공간과 세션 루트가 서로 다른 절대 경로인지 확인합니다.
- [ ] 새 세션 식별자로 단일 파일 변경 작업을 실행합니다.
- [ ] 최종 응답, 작업 공간 경로, 변경 파일, 셸 결과를 저장합니다.
- [ ] 실행 중인 SDK 프로세스를 강제 종료합니다.
- [ ] 같은 세션을 바로 재실행하지 않고 기록과 파일 상태를 먼저 비교합니다.
- [ ] 원격 접속을 끊었다가 다시 연결해 프로세스와 로그 상태를 확인합니다.
- [ ] 맥을 재시작한 뒤 실행 계정, 환경 변수, 가상 환경 경로를 검증합니다.
- [ ] 미완료 작업을 자동으로 반복하지 않고 재개 여부를 승인합니다.
- [ ] SDK와 런타임 버전, 백업 범위, 되돌릴 버전을 문서에 고정합니다.
현재 방식과 클라우드 맥을 비교해 결정합니다
로컬 맥에서 계속 실행하는 방식은 물리 장치와 파일 접근을 직접 통제할 수 있다는 장점이 있습니다. 그러나 절전, 네트워크 변경, 개인 작업과의 자원 충돌, 재부팅 뒤 수동 복구라는 운영 부담이 남습니다. 일반 클라우드 서버는 자동화에 익숙하지만, 맥 전용 도구와 애플 실리콘 조건을 별도로 확인해야 하고 원격 화면과 파일 권한 구성이 복잡해질 수 있습니다.
반면 MACGPU의 클라우드 맥을 사용하면 별도 개발 장비를 계속 켜 두지 않고, 위에서 정의한 가상 환경·작업 공간·세션 루트 구조를 독립된 원격 환경에 적용할 수 있습니다. 다만 장기간 고정된 고부하 작업, 물리 포트가 필요한 업무, 운영자가 직접 하드웨어를 관리해야 하는 경우에는 자체 장비가 더 적합할 수 있습니다. 임시 테스트나 검증 기간이라면 MACGPU의 클라우드 맥 환경에서 먼저 배포 절차를 검증하고, 필요한 경우 서울 지역 맥 대여 옵션을 확인하는 순서가 현실적입니다.
최소 SDK 작업을 통과한 뒤에는 작업 공간, 세션 루트, 인증 정보, 재시작 체크리스트가 모두 같은 운영 문서에 들어 있는지 확인하십시오. 그 조건을 충족하고도 장기간 장비가 필요할 때만 렌탈 기간을 늘리는 것이, 설치만 끝내고 복구 책임을 뒤늦게 떠안는 것보다 안전합니다.