10월 17일, DeepSeek가 두 개의 새 API를 모든 개발자에게 열었습니다. Search API와 Fetch API입니다. 사내 검색 엔진으로 웹을 찾아주고, 그 페이지의 본문을 Markdown으로 떠옵니다.

이 릴리스가 흥미로운 이유는 성능이 아니라 과금 구조입니다. 두 API 모두 토큰이 아니라 요청 단위로 과금됩니다. 검색 성공 1,000건당 0.75달러, 본문 추출 성공 1,000건당 0.75달러입니다. 결과가 없는 검색이나 실패한 요청은 청구되지 않습니다.

에이전트에 최신 웹 정보를 붙이는 일은 지금까지 애매했습니다. 검색 API를 별도로 붙이고, 크롤러를 관리하고, 본문을 파싱하고, 그 비용을 추정해야 했습니다. DeepSeek는 그 앞단을 하나의 요금표로 정리해 내놓았습니다.

두 API가 하는 일

공식 문서 기준으로 정리하면 이렇습니다.

[Search API]
POST https://api.deepseek.com/v1/tools/search

- 사내 검색 엔진이 쿼리에 맞는 웹페이지를 찾아 구조화된 결과로 반환
- 결과 항목마다 제목·URL·요약·발행일·사이트·권위 등급 포함

[Fetch API]
POST https://api.deepseek.com/v1/tools/fetch

- 단일 웹페이지를 가져와 제목과 본문을 Markdown으로 반환
- 사이트 접근 정책의 영향을 받는다

[공통]
- Bearer 인증 (기존 DeepSeek API 키와 동일)
- 순수 JSON API, 읽기 전용

Search 요청에는 이런 필드를 씁니다.

필드 필수 기본값 설명
query 예 — 1~128자. 검색 연산자 지원
count 아니오 10 결과 수 1~50. 가격과는 무관
ori_question 아니오 — 검색을 유도한 원래 질문. 쿼리 이해 보조
localization 아니오 "" 결과를 현지화할 IP 주소
need_content 아니오 false true면 content에 페이지 본문 포함

응답은 results 배열입니다. 각 항목의 필드가 실무적으로 중요합니다.

rerank_score : 0~3. 관련성·권위·최신성을 합친 점수
               (1.5 이상이면 고품질 결과로 간주)
title        : 결과 제목
url          : 결과 URL
snippet      : UI 표시용 짧은 요약 (보통 100~200자)
summary      : 모델이 읽도록 만든 긴 요약 (보통 600~800자)
content      : 페이지 본문 (need_content=false면 빈 문자열)
site_name    : 사이트 이름 (없으면 null)
date         : 발행 시각, RFC 3339 (모르면 null)
authority    : 권위 등급 0~4 (-1은 알 수 없음, 3 이상은 고권위)

여기서 눈여겨볼 점은 summary와 authority입니다. summary는 사람이 아니라 모델이 읽도록 만든 600~800자 요약입니다. 즉 검색 결과를 그대로 프롬프트에 넣어도 토큰이 비교적 예측 가능합니다. authority는 출처를 걸러내는 기준이 됩니다. "3 이상만 인용하라" 같은 규칙을 코드로 강제할 수 있습니다.

검색 연산자도 쓸 수 있습니다.

site:github.com      특정 사이트만
-site:example.com    특정 사이트 제외
"exact phrase"       정확한 문구
-"release notes"     특정 문구 제외
lang:zh,en           언어 제한
after:2025-01-01     이 날짜 이후 발행
before:2026-06-01    이 날짜 이전 발행

조합 예:
"DeepSeek site:github.com OR site:huggingface.co lang:en after:2025"

Fetch는 단순합니다. url 하나를 받아 title과 content(Markdown)를 돌려줍니다. URL은 8,192자 이하의 HTTP·HTTPS여야 하고, 사용자 이름이나 비밀번호를 포함하면 안 됩니다.

파이프라인: 벡터 DB 없이 시작하는 RAG

두 API를 이어 붙이면 가장 단순한 형태의 검색 증강 흐름이 됩니다.

[사용자 질문]
     ↓
① [Search API]  query + ori_question
     ↓
   결과 목록 (제목·요약·URL·authority·rerank_score)
     ↓
② 필요하면 [Fetch API]로 상위 페이지만 본문 확보
     ↓
③ 출처(URL·date·authority)를 붙여 LLM에 전달
     ↓
④ 인용이 포함된 답변 생성

이 구조의 장점은 명확합니다. 문서를 미리 임베딩해 둘 필요가 없고, 인덱스를 최신으로 유지할 필요도 없습니다. 질문이 들어올 때마다 실시간 웹을 검색하므로, "어제 공개된 릴리스"처럼 색인 시점에 따라 답이 달라지는 질문에 강합니다. 전통적인 RAG와의 차이는 고전 RAG에서 에이전트 RAG로에서 다뤘습니다.

비용을 계산해 보자

여기가 이 API의 핵심입니다. 과금 단위가 요청이라는 점을 정확히 이해해야 합니다.

[Search]  성공한 요청 1,000건당 $0.75
[Fetch]   성공한 요청 1,000건당 $0.75

청구되는 경우
- HTTP 200 이면서 결과가 나온 경우
  · Search: results 배열이 비어 있지 않을 때
  · Fetch: 페이지 본문을 반환했을 때

청구되지 않는 경우
- 실패한 요청
- 결과가 없는 검색 (빈 배열)
- 타임아웃

count(결과 개수)는 가격에 영향을 주지 않습니다. 5개를 받든 50개를 받든 요청 하나는 요청 하나입니다. 그래서 "일단 50개 받아두고 골라 쓰기"가 비용상 합리적일 수 있습니다.

질문 하나를 처리하는 비용을 어림해 보겠습니다.

[에이전트가 질문 하나에 도구를 3번 쓴다고 가정]

검색 2회 → $0.75 × 2 / 1,000 = $0.0015
본문 3회 → $0.75 × 3 / 1,000 = $0.00225
                            ─────────────
도구 비용 소계              약 $0.00375

+ LLM 토큰 비용 (별도 계산)

즉 도구 비용은 질문당 1센트도 되지 않습니다. 검색·추출을 몇 번 하든 비용은 거의 고정이고, 실제 비용을 좌우하는 것은 그 뒤의 LLM 토큰입니다. 이것이 이 설계의 요점입니다. 프롬프트에 넣을 본문을 미리 정제(요약·본문 추출)해 두면, 비싼 토큰을 아낄 수 있습니다.

한 가지 중요한 예외가 문서에 명시되어 있습니다.

DeepSeek Harness, Claude Code, Codex를 통해 DeepSeek API를 쓰면
서버 측 도구 호출이 이미 Search·Fetch를 사용한다.
이 호출들은 현재 무료이며,
2026년 11월 1일 00:00(베이징 시간)부터 요청당 과금이 시작된다.

전: 실무에서 걸리는 지점

좋은 점만 보면 균형이 깨집니다. 실제로 붙여 보면 마주칠 제약들입니다.

첫째, QPS 제한입니다. 계정 단위로 Search와 Fetch가 각각 초당 5회로 제한됩니다. API 키를 바꿔도 계정 단위로 계산되며, 모델 동시성 제한과는 별개입니다. Fetch는 도메인별 QPS 제한도 추가로 받습니다. 즉 한 사이트에서 여러 페이지를 빠르게 긁으려는 계획은 429에 부딪힙니다.

둘째, 재시도 규칙입니다. 문서는 이렇게 안내합니다.

408, 429, 5xx  → 기다렸다가 재시도
402            → 잔액 충전 후 재시도
그 외 4xx      → 요청을 바꾸지 않고 재시도하지 말 것
403            → Fetch가 보안 정책에 의해 거부됨
404            → 사용 가능한 본문을 못 가져옴

셋째, Fetch는 사이트 정책에 종속됩니다. 404에는 "URL이 없음"뿐 아니라 "사이트 정책으로 차단", "지원하지 않는 콘텐츠 타입", "추출 가능한 Markdown이 없음"이 모두 포함됩니다. 검색은 성공했는데 본문 추출은 실패하는 경우가 실제로 흔하다고 보는 게 안전합니다.

넷째, 품질 판단은 내 몫입니다. rerank_score와 authority는 신호일 뿐입니다. 검색 결과가 비어 있으면 청구되지 않지만, 그건 "좋은 결과가 없다"가 아니라 "이 쿼리로는 아무것도 못 찾았다"일 수 있습니다. 쿼리를 바꿔 여러 번 시도하는 전략이 필요합니다.

결론: 검색 파이프라인 미니 프로토콜

브리핑의 액션을 그대로 실험으로 옮기면 이렇습니다.

[Search → Fetch → 출처 확인 → 요약, 미니 프로토콜]

1. 도구 호출 예산을 정한다
   [ ] 질문당 검색 최대 N회, 본문 최대 M회
   [ ] 계정 QPS(초당 5회)를 넘지 않도록 큐를 둔다

2. 검색 결과를 규칙으로 거른다
   [ ] rerank_score ≥ 1.5
   [ ] authority ≥ 3 (인용 가능한 출처)
   [ ] 발행일이 필요한 기간 안인지 확인

3. 본문은 필요한 페이지만 가져온다
   [ ] 상위 1~2개만 Fetch
   [ ] 404면 조용히 건너뛰고 다음 결과로

4. 답변에 출처를 강제한다
   [ ] 문장마다 URL·발행일을 붙인다
   [ ] authority 낮은 출처는 "확인 필요"로 표시

5. 세 가지를 기록한다
   [ ] 도구 비용 (요청 수 × $0.00075)
   [ ] LLM 토큰 비용
   [ ] 검색 정확도 (답에 실제로 쓰인 출처 비율)

핵심 문장은 이렇습니다.

검색과 본문 추출이 요청 단위로 과금되면,
비용을 결정하는 것은 검색 횟수가 아니라
그 뒤에 붙는 토큰이다.

그래서 이 API는 "싸게 검색하는 법"이 아니라 "비싼 토큰에 넣을 재료를 싸게 마련하는 법"으로 읽어야 합니다. 파이프라인을 만들고 요청당 비용과 검색 정확도를 함께 재보면, 에이전트에 웹을 붙이는 감이 훨씬 빨리 잡힙니다. 검색의 기본 개념부터 다시 보고 싶다면 RAG란 무엇인가와 문서 RAG와 OCR 파이프라인을 이어 보면 좋습니다.

함께 읽으면 좋은 글

참고 자료

이 주제를 직접 따라가며 배우고 싶다면

검색과 본문 추출을 직접 붙여 보는 일은 RAG 파이프라인을 손으로 만들어 볼 때 가장 빨리 익숙해집니다. 검색·청킹·인용·평가까지 한 흐름으로 다뤄 보면, 어디서 품질이 깨지는지 감이 옵니다.