DeepSeek Search·Fetch API 사용법: 웹 검색 구현과 비용 계산

DeepSeek Search API는 질문에 맞는 웹페이지를 찾고, Fetch API는 선택한 페이지의 본문을 Markdown으로 가져온다. 모델 답변 생성과는 별도 요청이다. 에이전트에 연결하려면 ‘검색 → 원문 선택 → 본문 수집 → 근거 확인 → 답변’ 흐름을 구성하고, 검색·수집 비용과 모델 토큰 비용을 따로 계산해야 한다.

공개 발표는 2026년 10월 17일이며, 이 글의 문서 확인·발행일은 10월 20일이다. 19일 브리핑에서 분리한 공식 문서 기반 가이드다. 유료 API 호출과 검색 품질 평가는 수행하지 않았으며 아래 코드는 구현 예시다. 코딩 모델 자체의 설정은 V4.1 Flash 1017 전환 가이드에서 다룬다.

Search와 Fetch는 언제 각각 호출하나

필요한 작업	사용할 API	반환 정보
어떤 문서를 읽을지 찾기	`POST /v1/tools/search`	URL·제목·요약 등을 포함한 `results`
선택한 문서의 본문 읽기	`POST /v1/tools/fetch`	`title`, Markdown 형식의 `content`

두 API는 https://api.deepseek.com 아래에 있고 DeepSeek 키의 Bearer 인증을 사용한다. Search 요청은 query가 필수이고 count로 결과 수를 지정한다. need_content: true로 본문도 요청할 수 있지만, 본문을 얻지 못한 결과에서는 content가 비어 있을 수 있다. Search 사용 안내

따라서 모든 결과에 Fetch를 기계적으로 붙일 필요는 없다. 먼저 질문과 관련된 원문을 선택하고, 이미 충분한 본문이 있으면 재수집을 생략하는 구조를 고려할 수 있다. 이때도 검색 요약과 원문 본문은 구분해서 저장한다.

Node.js에서 검색 후 공식 문서 두 개만 수집하는 예시

다음은 Node.js 18 이상의 내장 fetch를 사용하는 .mjs 예시다. 별도 패키지나 모델 SDK가 필요 없다. DEEPSEEK_API_KEY는 셸 환경 변수로 설정한다. 이 예시를 실행하면 일반 API의 과금 대상 요청이 발생할 수 있다.

// search-docs.mjs — 실제 API에서는 실행하지 않은 예시
const apiKey = process.env.DEEPSEEK_API_KEY
if (!apiKey) throw new Error('DEEPSEEK_API_KEY가 필요합니다.')
 
async function callTool(name, body) {
  const response = await fetch(`https://api.deepseek.com/v1/tools/${name}`, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${apiKey}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(body),
    signal: AbortSignal.timeout(30000),
  })
  if (!response.ok) {
    throw new Error(`${name} 요청 실패: HTTP ${response.status}`)
  }
  return response.json()
}
 
const { results } = await callTool('search', {
  query: 'DeepSeek V4.1 site:api-docs.deepseek.com',
  count: 5,
  need_content: false,
})
 
const selected = results.filter((result) => {
  try {
    const url = new URL(result.url)
    return url.protocol === 'https:' && url.hostname === 'api-docs.deepseek.com'
  } catch {
    return false
  }
}).slice(0, 2)
 
const pages = []
for (const result of selected) {
  const page = await callTool('fetch', { url: result.url })
  if (!page.content?.trim()) continue
  pages.push({
    url: result.url,
    title: page.title || result.title,
    publishedAt: result.date,
    retrievedAt: new Date().toISOString(),
    content: page.content,
  })
}
console.log(JSON.stringify(pages, null, 2))

리뷰할 요청·응답 형식은 Search API 명세와 Fetch API 명세를 따른다. 예시의 ‘공식 도메인만 선택’, ‘최대 두 페이지’, ‘30초 제한’은 이 글에서 정한 구현 선택이며 DeepSeek의 고정 요구사항이 아니다. 자동 재시도와 LLM 답변 생성은 포함하지 않았다.

실행 후에는 pages가 비었는지, 본문이 질문을 뒷받침하는지 확인해야 한다. 빈 결과를 ‘그 사실이 존재하지 않는다’는 결론으로 바꾸면 안 된다. 날짜가 null인 문서는 발행일을 추정하지 않고 수집 시각과 분리한다. LLM에 전달할 때는 본문을 외부 자료로 취급하고, 페이지에 섞인 명령을 도구 실행 지시로 사용하지 않는 편이 좋다.

검색 연산자와 결과 점수는 선택을 돕는 신호다

Search 명세상 query는 1~~128자, count는 1~~50이며 기본은 10이다. 지원 연산자에는 site:, -site:, 인용부호, lang:, after:, before: 등이 있다. 예를 들어 DeepSeek site:api-docs.deepseek.com after:2026-10-01처럼 범위를 좁힐 수 있다. 연산자 안내

결과의 rerank_score는 관련성·권위·신선도 등을 결합한 점수이며 authority도 검색 서비스의 분류다. 높은 점수가 특정 문장의 사실성을 검증했다는 뜻은 아니다. 검색 결과가 가리키는 원문에서 발표일·대상 버전·제공 조건을 다시 읽어야 한다.

실제 서비스에 넣기 전에는 다음과 같은 질문 묶음으로 평가하는 것을 제안한다.

질문 유형	확인할 결과
특정 API의 설정 방법	공식 문서에 도달하고 코드의 대상 버전을 구분하는가
과거 날짜의 출시 상태	나중에 갱신된 내용을 당시 사실로 혼동하지 않는가
한국어 제품 질문	관련 한국어·영문 원문을 찾고 설명을 연결할 수 있는가
결과가 없거나 접근이 막힌 질문	확인 불가 상태를 그대로 사용자에게 전달하는가

이는 검색 서비스의 우열을 판정한 결과가 아니라 도입 전에 사용할 평가 설계다.

비용은 결과 개수가 아니라 과금 대상 요청 수로 계산한다

공식 가격표는 Search와 Fetch를 각각 성공 요청 1,000회당 $0.75로 안내한다. 사용 가이드의 과금 조건에 따르면 HTTP 200이면서 Search가 비어 있지 않은 결과를 반환하거나 Fetch가 본문을 반환할 때 과금된다. 실패·빈 검색 결과·타임아웃은 과금하지 않으며 count는 요청당 가격을 바꾸지 않는다.

아래는 모든 호출이 과금 대상이고 별도 무료 혜택이 없다고 가정한 계산이다. 모델 입력·출력 토큰, 저장·네트워크 비용은 포함하지 않았다.

작업 1건의 호출 구성	1건 비용	같은 작업 1,000건	같은 작업 10만 건
Search 1회	$0.00075	$0.75	$75
Search 1회 + Fetch 2회	$0.00225	$2.25	$225
Search 1회 + Fetch 3회	$0.00300	$3.00	$300

계산식은 ($0.75 ÷ 1,000) × (과금 Search 수 + 과금 Fetch 수)다. 검색 한 번에 결과 다섯 개를 받는 것과 Fetch 다섯 번은 다르다. 수집한 본문을 LLM에 넘기면 그 텍스트는 모델 입력 비용에 영향을 줄 수 있으므로 요청 비용만으로 에이전트의 전체 원가를 계산해서는 안 된다.

도구 통합의 한시 무료 조건은 일반 API와 구분한다

20일 확인한 17일 발표문은 DeepSeek API 사용자가 DeepSeek Harness·Claude Code·Codex를 통해 호출하는 서버 측 Search·Fetch 도구의 과금 시작을 2026년 10월 31일 16:00 UTC로 안내한다. 현재 가격표와 가이드의 11월 1일 00:00 베이징 시간은 같은 시점이며, 한국시간으로 11월 1일 01:00 KST다.

19일 GPT 자료에는 문서 사이의 일정 표현 차이가 남아 있었지만, 이번 확인에서는 두 안내가 일치했다. 이 무료 조건을 일반 REST 호출 전체에 적용하거나 LLM 토큰까지 무료라고 해석해서는 안 된다. 실제 사용하는 경로와 청구 내역을 확인해야 한다.

오류가 나면 재시도 전에 원인을 구분한다

공식 오류 안내를 기준으로 운영 흐름을 나누면 다음과 같다. 횟수·대기시간 상한은 서비스의 허용 지연과 예산에 맞춰 정한다.

응답	처리 방향
HTTP 200, 빈 `results`	정상적인 무검색 결과다. 질문 범위를 바꾸거나 확인 불가로 처리한다.
400·401·402	요청 값·인증·잔액을 먼저 고친다. 같은 요청을 반복하지 않는다.
Fetch 403·404	보안·접근 정책이나 본문 추출 가능 여부를 확인한다. 다른 허용 원문을 찾는다.
408·429·5xx	대기 후 제한적으로 재시도한다. 대기 간격을 늘리고 전체 시도 예산을 둔다.

Search와 Fetch에는 계정 단위의 별도 QPS 제한이 있고 Fetch는 대상 도메인 제한도 받는다. 키를 바꾸는 것으로 계정 제한을 해결하려 하지 말고 요청 빈도와 중복 수집을 관리한다. 성공 기준은 호출 횟수가 아니라 검증할 수 있는 출처와 함께 질문에 답했는가다.

참고 자료

Search & Fetch 사용 가이드 — DeepSeek, 확인일 2026-10-20
Search API 명세 — DeepSeek, 확인일 2026-10-20
Fetch API 명세 — DeepSeek, 확인일 2026-10-20
Models & Pricing — DeepSeek, 확인일 2026-10-20
Search·Fetch 공개와 통합 경로 과금 일정 — DeepSeek, 2026-10-17, 재확인일 2026-10-20