이 글에서 가장 먼저 확인할 것은 무엇인가요?

실행 프로그램과 확장

최종 업데이트 2026-10-30

DeepSeek Search·Fetch API: 로컬 LLM에 웹 검색 붙이기

검색과 페이지 가져오기를 나눠 호출하고, 결과 요약을 로컬 모델의 입력에 넣어요.

DeepSeek이 연 Search API¹는 질의에 맞는 웹 문서 목록을, Fetch API는 지정한 페이지의 본문을 Markdown으로 돌려줘요. 둘 다 같은 API 키를 쓰고 성공한 요청 1,000건당 각각 $0.75예요. 로컬 모델에는 도구 호출²을 강제하지 말고, 앱이 먼저 검색해 상위 결과의 요약과 URL을 프롬프트³에 넣는 방식이 단순하고 재현하기 쉬워요.

실행 조건과 핵심 내용

Search는 /v1/tools/search, Fetch는 /v1/tools/fetch이고 둘 다 Bearer 인증을 써요.
성공한 요청 1,000건당 각각 $0.75이고, Harness·Claude Code·Codex 경유는 11월 1일까지 무료예요.
로컬 모델에는 도구 호출 대신 검색 요약을 프롬프트로 넣는 편이 안정적이에요.

검색과 페이지 가져오기는 별도 API예요

Search API는 질의에 맞는 웹 문서 목록을 돌려주고, Fetch API는 지정한 URL 한 개의 본문을 Markdown으로 가져와요. 둘 다 https://api.deepseek.com 아래 /v1/tools/search와 /v1/tools/fetch에 있고, DeepSeek API 키를 Bearer로 씁니다. 검색만으로는 페이지 전문을 얻지 못하므로, 요약으로 충분한지 원문이 필요한지 먼저 정하세요.

검색은 질의 1~128자, 결과 1~50개(기본 10개)를 받아요. need_content를 켜면 결과에 페이지 본문이 함께 오지만 그만큼 응답이 커집니다. ori_question에는 검색을 부른 원래 질문을 128자까지 넣어 순위를 보정할 수 있어요.

책상 위에 놓인 문서 더미와 여러 장의 카드, 카드에서 화살표가 뻗어 다른 카드로 이어지는 그림 — 검색 결과는 문서 목록이고, 원문은 Fetch로 따로 가져와요.

응답에서는 순위 점수와 요약을 먼저 봐요

각 결과에는 rerank_score(0~3), authority(0~4), date, summary(보통 600~800자), content가 들어 있어요. 1.5 이상이면 관련성이 높은 편으로 안내되고, authority 3 이상은 신뢰도가 높은 출처로 표시됩니다. 모델에 넣을 때는 summary와 URL, 날짜를 함께 남기면 출처를 붙이기 쉬워요.

Search 응답에서 자주 쓰는 필드
필드	값	쓰임
`rerank_score`	0~3	상위 결과를 고르는 기준
`authority`	0~4	출처 신뢰도 표시
`summary`	600~800자	프롬프트에 넣을 요약
`content`	`need_content`일 때	원문 일부 확인

Search·Fetch API 안내

로컬 모델에는 검색 결과를 프롬프트로 넣어요

로컬 모델에 도구 호출을 맡기면 작은 모델일수록 스키마를 어기거나 같은 호출을 반복하는 일이 생겨요. 대신 앱이 먼저 검색하고 상위 3~5개의 summary를 인용 번호와 함께 프롬프트에 넣은 뒤, 로컬 모델에는 '주어진 자료만으로 답하고 없는 내용은 모른다고 말하기'를 요청하는 방식이 단순합니다.

원문이 필요한 질문은 고른 결과의 URL만 Fetch로 가져와 본문을 잘라 넣어요. 페이지가 길면 질문과 관련된 문단만 남기고, 문서마다 URL과 가져온 시각을 기록하세요. 이렇게 하면 모델을 바꿔도 검색 부분은 그대로 재사용할 수 있어요.

Search API 호출 예시

curl https://api.deepseek.com/v1/tools/search \
  -H "Authorization: Bearer $DEEPSEEK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"DeepSeek V4.1 Flash 1017","count":5}'

키는 환경변수에서 읽고 셸 기록에 남기지 마세요. 결과의 summary와 URL을 프롬프트에 넣기 전에 길이를 확인합니다.

비용은 성공한 요청을 기준으로 붙어요

Search와 Fetch는 각각 성공한 요청 1,000건당 $0.75예요. 하루 40번 검색하고 20번 원문을 가져오면 한 달에 검색 1,200건, Fetch 600건으로 약 $1.35입니다. 실패한 요청은 과금 대상이 아니라고 안내되어 있지만, 재시도가 성공하면 그만큼 계산에 들어가요.

DeepSeek Harness, Claude Code, Codex에서 서버 도구로 호출하는 경우는 2026년 11월 1일 0시(베이징 시간)까지 무료예요. 그 뒤에는 같은 요청도 건당 과금되므로, 무료 기간에 호출량을 기록해 두면 전환 뒤 비용을 가늠하기 쉬워요.

Search·Fetch 요금
API	단위	가격
Search	성공 1,000건	$0.75
Fetch	성공 1,000건	$0.75

한 장의 긴 문서가 여러 장의 작은 카드로 나뉘어 책상 위에 늘어선 그림 — 긴 페이지는 필요한 부분만 잘라 넣으면 토큰을 아낄 수 있어요.

Fetch가 실패하는 경우를 나눠서 처리해요

Fetch는 대상 사이트가 막으면 403, 쓸 만한 본문을 얻지 못하면 404, 주소를 해석할 수 없으면 500을 돌려줄 수 있어요. 잔액이 없으면 402예요. 403과 404는 같은 주소로 다시 시도해도 결과가 같을 가능성이 크므로, 다른 출처를 찾거나 검색 요약으로 대체하세요.

URL에 사용자 이름이나 비밀번호를 넣을 수 없고, 사이트의 접근 정책을 우회하는 용도로 쓰면 안 됩니다. 재시도는 5xx에만 짧게 제한하고, 성공한 URL과 본문 해시를 캐시에 남기면 같은 페이지를 반복해서 가져오는 비용을 줄일 수 있어요.

운영에 붙이기 전에 남길 기록

질의, 선택한 URL, 가져온 시각, 사용한 모델과 프롬프트 버전을 한 줄씩 남기세요. 검색 결과는 시간이 지나면 바뀌므로, 같은 질문에 다른 답이 나왔을 때 검색 시점의 자료를 확인할 수 있어야 합니다. 개인정보나 사내 문서를 질의에 넣을 때는 외부로 나가는 범위를 먼저 정하세요.

책상 위 카드들이 화살표로 이어지다 빨간 X 표시에서 끊기는 그림 — 가져오지 못한 페이지는 같은 주소로 반복하지 말고 다른 출처로 바꿔요.

용어 각주

API — 프로그램의 기능을 다른 코드에서 호출하기 위한 약속된 인터페이스입니다.
본문으로 돌아가기
도구 호출 — 모델이 파일 읽기·검색·명령 실행 같은 외부 기능의 이름과 인자를 요청하는 형식입니다. 요청을 실제로 실행할지는 에이전트 런타임과 권한 설정이 결정합니다.
본문으로 돌아가기
프롬프트 — 모델에 보내는 입력문입니다. 생성 모델에서는 만들 결과를 설명하는 문장이 되어 출력의 구성과 내용을 크게 좌우합니다.
본문으로 돌아가기

자주 묻는 질문

이 글에서 가장 먼저 확인할 것은 무엇인가요?: DeepSeek이 연 Search API는 질의에 맞는 웹 문서 목록을, Fetch API는 지정한 페이지의 본문을 Markdown으로 돌려줘요. 둘 다 같은 API 키를 쓰고 성공한 요청 1,000건당 각각 $0.75예요. 로컬 모델에는 도구 호출을 강제하지 말고, 앱이 먼저 검색해 상위 결과의 요약과 URL을 프롬프트에 넣는 방식이 단순하고 재현하기 쉬워요.