DeepSeek 웹 검색 및 가져오기
직접 검색, 페이지 가져오기 또는 모델의 웹 도구 실행 중 알맞은 방식을 선택합니다.
호출 방식 선택
| 요구 사항 | 호출 방식 |
|---|---|
| 키워드로 페이지를 찾고 결과를 직접 처리 | Search는 링크, 요약과 선택적 본문을 반환. model 불필요 |
| URL이 있고 본문을 읽으려는 경우 | Fetch는 제목과 Markdown 본문을 반환. model 불필요 |
| 모델이 자료를 찾아 바로 답변하게 하려는 경우 | Responses 또는 Messages로 서버 측 웹 도구를 선언하면 모델이 작업을 선택하고 실행 |
다음 요청은 플랫폼 API Key를 사용합니다. 독립 API와 모델 도구 모두 호출 요금이 발생할 수 있습니다.
직접 검색하고 가져오기
1. 웹 검색
curl 'https://api.agtcloud.cn/v1/tools/search' \
-H 'Authorization: Bearer your-api-key' \
-H 'Content-Type: application/json' \
--data '{
"query": "DeepSeek site:api-docs.deepseek.com",
"count": 5,
"need_content": false
}'results에서 관련 페이지를 골라 url을 읽습니다. 일치하는 결과가 없으면 검색어나 범위를 조정합니다. 결과에 본문을 포함하려면 need_content: true를 설정합니다.
2. 선택한 페이지 가져오기
아래 URL을 이전 단계에서 선택한 results[].url로 바꿉니다.
curl 'https://api.agtcloud.cn/v1/tools/fetch' \
-H 'Authorization: Bearer your-api-key' \
-H 'Content-Type: application/json' \
--data '{
"url": "https://example.com/"
}'title과 content를 읽고 Markdown을 표시, 검색 또는 후속 모델 입력에 사용합니다. 성공한 검색과 가져오기는 각각 과금합니다. 검색 결과가 여러 개여도 검색 요청 한 건으로 계산합니다.
모델에서 웹 도구 사용
MODEL_ID를 해당 도구를 지원하는 모델의 전체 ID로 바꿉니다. 도구는 서버에서 실행되므로 클라이언트가 직접 검색하거나 도구 결과를 다시 보낼 필요가 없습니다.
deepseek-v4-pro를 선택합니다. web_search는 검색과 페이지 열기를 수행하므로 별도의 Fetch 도구 선언은 필요하지 않습니다.
curl 'https://api.agtcloud.cn/v1/responses' \
-H 'Authorization: Bearer your-api-key' \
-H 'Content-Type: application/json' \
--data '{
"model": "MODEL_ID",
"reasoning": {"effort": "none"},
"max_output_tokens": 4096,
"tools": [{"type": "web_search"}],
"input": "Python 공식 웹사이트를 검색하고 관련 페이지를 읽은 뒤 용도를 간단히 설명하고 출처 링크를 제공해 주세요."
}'전체 요청과 응답 구조는 Responses와 Messages를 참조하세요.
결과와 사용량 읽기
| 호출 방식 | 위치와 의미 |
|---|---|
| 독립 Search / Fetch | Search는 results, Fetch는 title/content를 읽음. 추가 usage는 반환하지 않음 |
| Responses 결과 | output의 web_search_call이 웹 작업을 설명하며 최종 답변은 message의 텍스트에 있음 |
| Responses 사용량 | usage.server_tool_use.tool_search는 성공한 검색 쿼리 수이며, 한 도구 호출에 여러 쿼리가 있으면 여러 번으로 계산할 수 있음. tool_fetch는 페이지 열기와 페이지 내 텍스트 찾기를 포함한 성공한 페이지 읽기 수임. 둘 다 영이면 server_tool_use를 생략 |
| Messages 결과 | content에 server_tool_use, web_search_tool_result와 최종 답변 텍스트 블록이 포함됨 |
| Messages 사용량 | usage.server_tool_use.web_search_requests는 실패나 max_uses 초과를 포함할 수 있는 시도 횟수임. tool_search는 결과가 있는 성공한 검색 수이며 플랫폼은 이 성공 횟수로 검색 요금을 계산 |
| 스트리밍 사용량 | Responses는 마지막 response.completed/incomplete/failed의 response.usage, Messages는 마지막 message_delta.usage의 누적 값을 읽음. 초기 이벤트 값과 합산하지 않음 |
도구를 선언해도 모델의 검색 실행이 보장되지는 않습니다. 실제 횟수는 반환된 사용량을 따릅니다. Responses는 max_tool_calls를 무시하며 프롬프트의 횟수 요구도 과금 횟수 상한이 아닙니다.