OpenAI 호환 API로 DeepSeek Harness 활용하기

DeepSeek Harness는 네 가지 값(기본 URL, API 키, 모델 ID, Chat Completions 경로)을 provider 플러그인에 제공하면 OpenAI 호환 모델 엔드포인트를 사용할 수 있습니다. reAPI의 경우 기본 URL은 https://api.reapi.ai/v1이고, 현재 모델 ID는 deepseek-v4-flash와 deepseek-v4-pro입니다.^[1]^[2]

Harness 프로젝트는 아직 개발자 미리보기(developer preview)로 표시되어 있으므로 명령어 이름과 설정 파일이 변경될 수 있습니다. 안정적인 부분은 provider 계약입니다. 먼저 해당 계약을 구성한 다음 추가 플러그인을 설치하기 전에 일반 메시지 하나와 도구 호출 하나를 확인하세요.

매핑할 네 가지 값

Harness provider 설정	reAPI 값
Provider 유형	OpenAI-compatible
Base URL	`https://api.reapi.ai/v1`
API 키	환경 변수에 저장된 reAPI API 키
Model	`deepseek-v4-flash` 또는 `deepseek-v4-pro`

API 키를 저장소 파일에 붙여넣지 마세요. Provider 플러그인은 현재 Harness 릴리스에서 지원하는 환경 변수 또는 보안 저장소에서 읽어야 합니다.

HTTP 계층에서 요청은 다음과 같이 해석됩니다:

POST https://api.reapi.ai/v1/chat/completions
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Harness 동작을 디버깅하기 전에 이 최소한의 body로 모델 접근성을 테스트하는 것만으로 충분합니다:

{
  "model": "deepseek-v4-flash",
  "messages": [
    { "role": "user", "content": "Reply with exactly: provider ok" }
  ],
  "stream": false,
  "max_tokens": 64
}

직접 요청이 실패하면 Harness는 문제가 아닙니다. 먼저 URL, 키, 모델 ID, 잔액 또는 네트워크 접근을 수정하세요.

Flash에서 시작하여 어려운 단계는 Pro로 승격하기

현재 두 DeepSeek V4 변형은 모두 1M 토큰 컨텍스트 윈도우, 최대 384K 출력, 도구 사용, 사고 모드, 비전 입력, 그리고 reAPI 경로의 컨텍스트 캐싱을 노출합니다.^[2] 가격과 의도된 워크로드는 크게 다릅니다.

Model	Cache-miss input / 1M	Cache-hit input / 1M	Output / 1M	첫 Harness 작업
DeepSeek V4 Flash	$0.14	$0.0028	$0.28	파일 검색, 요약, 일반적인 편집
DeepSeek V4 Pro	$1.74	$0.0145	$3.48	아키텍처, 어려운 디버깅, 긴 계획

에이전트 루프는 지시사항, 저장소 컨텍스트, 도구 스키마를 반복합니다. 이는 캐시 동작을 특히 중요하게 만듭니다. Flash cache-hit 입력은 cache-miss 입력보다 50배 저렴하고; Pro cache-hit 입력은 miss 입력보다 120배 저렴합니다.

에이전트를 연결하는 동안 Flash를 기본값으로 사용하세요. 그 단계의 추론 필요성이 대략 12.4배의 cache-miss 입력 요율과 출력 요율을 정당화할 때만 Pro로 라우팅하세요.

안정적인 접두사 유지하기

컨텍스트 캐싱은 연속된 요청의 시작이 동일하게 유지될 때 가장 유용합니다. 코딩 에이전트에서 해당 접두사는 종종 포함되어 있습니다:

시스템 지시사항;
저장소 정책;
도구 정의 및 JSON 스키마;
변경되지 않은 아키텍처 문서;
최신 도구 결과 이전의 대화.

도구를 재정렬하거나, 상단 근처에 타임스탬프를 추가하거나, 약간의 표현 변경으로 동일한 지시사항을 재생성하면 접두사 재사용을 방지할 수 있습니다. 변동 상태를 안정적인 블록 이후에 배치하세요.

예를 들어, 200,000개의 안정적인 입력 토큰, 10,000개의 새로운 입력 토큰, 8,000개의 출력 토큰이 있는 Pro 루프의 비용은 대략:

200,000 cached input × $0.0145 / 1,000,000 = $0.0029
 10,000 new input    × $1.74   / 1,000,000 = $0.0174
  8,000 output       × $3.48   / 1,000,000 = $0.02784
                                                -------
                                                $0.04814

캐시 히트 없이는 같은 210,000 입력 토큰이 출력 전에 $0.3654 비용이 들 것입니다. 에이전트의 컨텍스트 레이아웃은 최신 메시지에서 몇 백 토큰을 정리하는 것보다 중요할 수 있습니다.

플러그인을 추가하기 전에 도구 호출 확인하기

성공적인 채팅 응답은 에이전트가 작동할 수 있음을 증명하지 않습니다. 다음으로 무해한 도구 호출 테스트를 실행하세요:

{
  "model": "deepseek-v4-flash",
  "messages": [
    { "role": "user", "content": "What files are in the current directory?" }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "list_files",
        "description": "List files in the current working directory",
        "parameters": { "type": "object", "properties": {} }
      }
    }
  ],
  "tool_choice": "auto"
}

모델은 구조화된 도구 호출을 반환해야 합니다. Harness가 로컬 함수를 실행하고 다음 차례에 결과를 제공합니다. 모델이 산문으로 "파일을 나열할 것"이라고 인쇄하면 provider 플러그인이 tools를 전달했는지 확인하고 어시스턴트 도구 호출 필드가 그대로 반환되었는지 확인하세요.

모델 문제처럼 보이는 다섯 가지 실패점

증상	먼저 확인
401 응답	키가 없거나 Harness가 환경 변수를 상속받지 못했습니다
404 응답	Base URL 또는 `/v1/chat/completions` 경로가 중복/생략되었습니다
모델을 찾을 수 없음	정확한 `deepseek-v4-flash` 또는 `deepseek-v4-pro` ID를 사용하세요
에이전트가 말하지만 행동하지 않음	Provider 어댑터가 도구 정의 또는 도구 호출 출력을 누락했습니다
답변이 완료 전에 중지됨	사고가 출력 예산을 사용했습니다; `max_tokens`를 올리세요

사고는 현재 DeepSeek V4 경로에서 기본적으로 켜져 있습니다. 추론 토큰은 출력 사용량에 포함되므로 작은 출력 한계는 도구 계획이 사용자에게 표시되는 답변 전에 끝날 수 있습니다.^[2]

일회용 저장소로 전체 에이전트 루프 테스트하기

메시지 및 도구 호출 검사가 통과한 후 Harness에 통합 테스트용으로 생성한 작은 저장소를 제공하세요. 읽을 수 있는 파일, 실패한 테스트, 하나의 보호된 경로, 그리고 무해한 명령을 포함해야 합니다. 에이전트에게 테스트를 진단하고 패치를 제안한 뒤 좁은 검사를 실행하고 커밋이나 외부 작업 전에 중지하도록 요청하세요.

이는 JSON 도구 호출 테스트가 감지할 수 없는 네 가지 통합 실패를 나타냅니다:

상대 경로가 의도된 작업 디렉터리 밖으로 해석됩니다;
명령 출력이 모델이 오류를 보기 전에 잘립니다;
패치 도구가 줄 끝 또는 파일 인코딩을 변경합니다;
승인 경계가 UI에서는 적용되지만 플러그인에서는 적용되지 않습니다.

Harness를 재시작한 후 같은 작업을 반복하세요. 세션 복구는 코딩 에이전트에서 중요합니다. 왜냐하면 긴 실행은 일반적인 경계에서 실패하기 때문입니다: 랩톱 절전, 프로세스 재시작, provider 타임아웃, 또는 잘못된 도구 출력. 작동하는 첫 차례는 충분하지 않습니다.

런타임 및 모델 실패를 분리하기에 충분히 로깅하기

최소한, 요청 ID, 선택된 모델, 토큰 사용량, 캐시 히트 토큰, 종료 이유, 도구 이름, 도구 지속 시간, 그리고 편집된 오류를 유지하세요. API 키나 제한되지 않은 파일 콘텐츠를 로깅하지 마세요.

에이전트가 중지될 때, 이 필드들은 다른 질문에 답합니다:

관찰	가능성 있는 계층
모든 모델 출력 전에 HTTP 401/404	Provider 구성
`finish_reason: length`	출력 예산
유효한 도구 호출이지만 실행 없음	Harness/플러그인 런타임
도구 실행됨, 결과가 모델에 도달하지 않음	루프 직렬화
반복된 전체 입력(캐시 히트 없음)	컨텍스트 구성
올바른 스키마에도 불구하고 모델이 위험한 명령을 선택함	모델/프롬프트/승인 정책

이 분리 없이는 팀이 종종 누락된 환경 변수를 수정하기 위해 모델을 전환하거나 드롭된 도구 결과를 수정하기 위해 프롬프트를 다시 작성합니다.

숨겨진 추론을 대화 기록으로 전달하지 마세요

DeepSeek V4 응답은 최종 답변과 별도로 추론 콘텐츠를 포함할 수 있습니다. API 설명서는 다음 차례 전에 이전 추론 콘텐츠를 제거할 것을 권고합니다.^[2] 청구 및 디버깅에 필요한 내용을 제품의 정책에 따라 저장하되, 숨겨진 추론을 다음 사용자/어시스턴트 기록에 일반적인 콘텐츠인 것처럼 추가하지 마세요.

대화는 프로토콜에 필요한 표시되는 어시스턴트 응답, 구조화된 도구 호출, 도구 결과를 보존해야 합니다. 이는 다음 요청을 유효하게 유지하고 엔드포인트가 다시 받을 것으로 예상하지 않는 자료로 컨텍스트가 커지는 것을 방지합니다.