DeepResearch 실행 방법 5가지와 결과물, 도구 및 워크플로우

30일간의 검색 중 3일차.

연구 작업이 항상 보고서로 끝나는 것은 아닙니다. 사용자의 앱은 JSON을 필요로 할 수 있습니다. 분석가는 Excel 통합 문서를 필요로 할 수 있습니다. 팀 회의는 슬라이드를 필요로 할 수 있습니다.

검색은 매우 흔하고 인기 있는 기능입니다. 하지만 여러 단계의 검색과 분석을 활용하여 더 좋고 깊이 있는 연구-분석가 유형의 결과를 제공하는 흐름이 있습니다. 이것을 DeepResearch라고 부릅니다.

deep research를 사용하면 원하는 연구 깊이, 출력 형식, 생성할 파일, 에이전트가 사용할 도구를 선택할 수 있습니다. 또한 인간 검토를 위해 일시 중지하거나 재사용 가능한 워크플로우를 실행할 수도 있습니다.

이 가이드의 끝에 다다르면 다음을 알게 될 것입니다:

• 터미널에서 빠르고, 표준적이며, 무거운 deep research 실행 방법.
• PDF 보고서 또는 스키마 기반 구조화된 출력 요청 방법.
• CSV, Excel, Word, PowerPoint 및 PDF 결과물 생성 방법.
• 코드 실행, 스크린샷, 브라우저 사용 및 차트 활성화 방법.
• 인간 개입형 체크포인트(human-in-the-loop checkpoints)를 통해 계획과 출처 검토 방법.
• 재사용 가능한 연구 워크플로우 발견, 미리 보기 및 실행 방법.

이 글의 CLI 예제는 Valyu CLI 1.2.2를 사용합니다. Python 예제는 valyu 2.12.2를 사용합니다. 아래 모드 이름, 가격 및 기능 세부 정보는 현재 문서를 기준으로 확인되었습니다.

DeepResearch는 검색 결과가 아니라 연구 루프입니다

Search API는 애플리케이션이 사용할 결과를 반환합니다. DeepResearch는 더 광범위한 조사를 책임집니다: 검색 계획 수립, 출처 읽기, 격차(gap) 추적, 인용된 결과 작성까지 합니다.

개념적인 흐름은 다음과 같습니다:

Valyu는 학술 자료, 금융 자료, 의학 자료, 특허 자료 및 기타 전문화된 출처와 함께 웹 검색을 수행할 수 있습니다. 특정 실행에 사용할 수 있는 출처는 계정 접근 권한과 검색 설정에 따라 달라집니다.

작업(Tasks)은 비동기적입니다: 작업을 생성하고 ID를 저장한 다음, 기다리거나 웹훅 알림을 받습니다. 조사보다는 빠른 동기식 답변이 필요하다면 Answer API를 고려해 보세요.

세 가지 결정을 분리해서 기억하세요:

사전 준비 설정 (Prerequisite Setup).

사용 가능한 무료 크레딧을 가진 Valyu 계정이 필요합니다. platform.valyu.ai에서 접속하세요.

CLI 설치:

npm install -g @valyu/[email protected]
valyu login
valyu --version

... 또는 시스템에 맞는 최적의 CLI 설치 옵션을 사용하세요.

valyu login은 브라우저 인증 흐름(browser authentication flow)을 엽니다. 독립형 설치 옵션은 CLI 문서에 있습니다.

DeepResearch 실행 방법 5가지

1. Fast 모드: 집중적인 연구 질문에 답변하기

광범위한 조사가 아닌 제한적인 리서치 패스가 필요할 때는 fast를 사용합니다. 예를 들어, 특정 애플리케이션에 대한 두 가지 접근 방식을 비교하는 경우 다음과 같습니다:

valyu deepresearch create \
  "개발자 지원 어시스턴트를 위한 RAG와 파인튜닝(fine-tuning) 비교. 지식 업데이트 및 출처 인용에 중점을 둡니다." \
  --mode fast \
...

생성 시 작업 ID가 반환됩니다. 이를 아래 변수에 붙여넣으세요:

TASK_ID="반환된-작업-id를-붙여넣기"
valyu deepresearch watch "$TASK_ID" 

2. Standard mode: 더 광범위한 개요가 필요할 때 시작하세요

실용적인 제약 조건과 함께 더 넓은 비교가 필요할 때는 표준 모드(standard mode)를 사용합니다:

valyu deepresearch create \
  "개발자 지원 어시스턴트를 위한 RAG와 파인튜닝(fine-tuning) 비교. 신선도, 출처 인용, 유지보수 및 평가를 다룹니다." \
  --mode standard \
...

두 명령어 플래그 간의 차이점은 유용합니다:

• --research-strategy: 조사를 안내합니다. 무엇을 검토하고 어떤 증거를 우선순위로 둘지 결정합니다.
• --report-format: 결과를 안내합니다. 그 구조, 스타일 및 길이를 결정합니다.

일반적인 실행 시간은 10분에서 20분입니다. 보고서가 길기를 요청하는 것보다 범위가 잘 설정된 질문이 더 중요합니다.

3. Heavy mode: 더 많은 변수가 관련된 질문을 조사할 때

작업에 상충되는 증거, 여러 접근 방식 또는 상세한 리서치 검토가 포함될 때는 heavy를 사용하세요:

valyu deepresearch create
"개발자 지원을 위한 RAG, 파인튜닝 및 하이브리드 접근 방식 평가. 발표된 평가 결과, 실패 사례 및 운영상의 트레이드오프를 비교 분석합니다."
--mode heavy
...

헤비 모드는 약 90분이 소요됩니다.**

또한 포괄적인 연구를 위한 max 모드가 있습니다. 이 모드는 더 높은 기본 가격을 가지며 최소 $15의 사용 가능 크레딧이 필요합니다. 선택하기 전에 작업 범위를 확인하세요.

모드 비교

4. PDF 출력: 보고서 공유 용이화

API는 기본적으로 Markdown을 사용합니다. 앱에 사용할 텍스트와 독자를 위한 PDF를 모두 요청하려면 두 형식을 명시적으로 지정해야 합니다:

valyu deepresearch create \
  "개발자 지원을 위한 RAG 및 파인튜닝 비교. 증거 테이블과 인용문이 포함된 경영 요약서를 작성합니다." \
  --mode standard 
...

작업이 완료되면, 응답에는 output에 보고서가 포함되며, 성공적으로 생성될 경우 pdf_url에 PDF 링크가 포함됩니다.

PDF는 보고서 배포 방식을 변경합니다. 더 깊은 연구 모드를 선택하는 것은 아닙니다. CLI의 --no-pdf 플래그와 기본 형식 동작은 API의 Markdown 기본값과 별개입니다. 명시적인 형식이 이러한 모호성을 피할 수 있게 합니다.

5. 구조화된 출력: 애플리케이션에서 소비 가능한 데이터 반환

다음 단계가 대시보드, 데이터베이스 또는 다른 에이전트인 경우 JSON 스키마를 사용하세요. 이렇게 하면 추가적인 산문-데이터 추출 단계를 피할 수 있습니다.

이 예시는 별도의 Answer API가 아닌 DeepResearch를 실행합니다:

valyu deepresearch create
"개발자 지원을 위한 RAG와 파인튜닝 비교. 각 접근 방식, 최적의 사용 사례, 한계점, 그리고 지원하는 출처 URL을 반환하세요."
--mode standard
...

더 큰 스키마의 경우, JSON을 파일에 저장하고 --structured-file schema.json를 사용하세요.

스키마와 Markdown 또는 PDF 보고서 출력은 결합하지 마세요. 구조화된 출력(Structured output)은 대안적인 보고서 표현 방식입니다. 반환된 데이터를 검증하고 결정에 사용하기 전에 증거를 확인하세요.

DeepResearch는 또한 토큰 기반의 구조적 표현인 TOON도 지원합니다. TOON을 사용하려면 스키마가 필요합니다.

CLI에서는 --structured-file schema.json --output-format toon을 사용하세요. 기존 애플리케이션이 JSON을 예상하는 경우 JSON을 사용하고, TOON은 다른 파일 전달 유형이 아닌 선택적 표현 방식입니다.

결과물(Deliverables): 팀이 필요로 하는 파일을 생성하세요

보고서 형식(report format)이 주요 응답을 제어합니다. **결과물(Deliverables)**은 연구를 통해 생성되는 추가 파일들로, 각각 고유한 유형, 설명, 상태 및 다운로드 URL을 가집니다.

다음 다섯 가지 파일 유형을 모두 지정할 수 있습니다:

대기 옵션은 Python에서 초(seconds) 단위로 사용합니다. 7200은 2시간의 폴링 예산이며, 보장된 완료 시간을 의미하지 않습니다. 대기가 중단되면 작업 ID를 유지하고 다시 생성하기보다는 기존 실행 내역을 검사하세요.

보고서 상태뿐만 아니라 각 파일의 상태도 확인해야 합니다. 결과물 다운로드 URL은 서명되어 만료되므로 필요한 파일을 다운로드하여 보관하십시오.

도구: 에이전트가 계산하고, 페이지를 검사하며, 차트를 생성하도록 하세요

선택적 도구는 자유 형식 작업(freeform task)의 경우 기본적으로 비활성화되어 있습니다. 도구를 활성화하면 사용할 수 있게 되며, 에이전트가 이를 사용할지 여부를 결정합니다.