웹 검색 및 추출

anchor alias

anchor alias

anchor alias

웹 검색 및 추출

Hermes 에이전트는 여러 제공자가 지원하는 두 가지 모델 호출 가능 웹 도구를 포함합니다:

• web_search — 웹을 검색하고 순위가 매겨진 결과를 반환합니다
• web_extract — 하나 이상의 URL에서 읽을 수 있는 콘텐츠를 가져오고 추출합니다(백엔드가 제공하는 경우 내장된 딥 크롤링 지원 포함)

두 가지 모두 단일 백엔드 선택을 통해 구성됩니다. 제공자는 hermes tools를 통해 선택되거나 config.yaml에서 직접 설정됩니다. 재귀 크롤링 기능(Firecrawl/Tavily)은 별도의 web_crawl 도구가 아닌 web_extract를 통해 제공됩니다.

백엔드

제공자	환경 변수	검색	추출	기어가다	무료 등급
파이어크롤 (기본)	FIRECRAWL_API_KEY	✔	✔	✔	월 500크레딧
SearXNG	SEARXNG_URL	✔	—	—	✔ 무료(셀프 호스팅)
타빌리	TAVILY_API_KEY	✔	✔	✔	월 1,000회 검색
엑사	EXA_API_KEY	✔	✔	—	월 1,000회 검색
평행	PARALLEL_API_KEY	✔	✔	—	유료

기능별 분리: 검색과 추출에 대해 서로 다른 제공자를 독립적으로 사용할 수 있습니다 — 예를 들어 검색에는 SearXNG(무료)를 사용하고 추출에는 Firecrawl을 사용할 수 있습니다. 아래 기능별 구성을 참조하세요.

Nous Subscribers

유료 Nous Portal 구독이 있는 경우, 관리되는 Firecrawl을 통해 **Tool Gateway**에서 웹 검색 및 추출을 사용할 수 있으며, API 키는 필요하지 않습니다. 이를 활성화하려면 hermes tools을 실행하세요.

---

web_extract가 긴 페이지를 처리하는 방법

백엔드는 원시 페이지 마크다운을 반환하는데, 이는 방대할 수 있습니다(포럼 스레드, 문서 사이트, 댓글이 포함된 뉴스 기사 등). 컨텍스트 창을 사용 가능하게 유지하고 비용을 절감하기 위해, web_extract는 에이전트에 전달하기 전에 반환된 콘텐츠를 web_extract 보조 모델을 통해 처리합니다. 동작은 전적으로 크기 기반입니다:

페이지 크기(문자 수)	처리 방식
5,000 미만	그대로 반환됨 — LLM 호출 없음, 전체 마크다운이 에이전트에 도달함
5 000 – 500 000	web_extract 보조 모델을 통해 단일 통과 요약, 출력은 약 5,000자까지 제한
500 000 – 2 000 000	100k자 단위로 나누어 각 부분을 병렬로 요약한 후, 최종 요약(~5,000자)을 종합합니다
2,000,000 이상	집중 추출 지침이나 더 구체적인 소스와 함께 web_crawl을 사용하라는 힌트와 함께 거부됨

요약은 인용문, 코드 블록, 주요 사실을 원래 형식대로 유지합니다. 내용을 압축하는 기능이지, 문장을 새로 써주는 도구는 아닙니다. 요약이 실패하거나 시간이 초과되면 Hermes는 불필요한 오류 대신 원본 콘텐츠의 처음 약 5,000자를 표시합니다.

어떤 모델이 요약을 하나요?

web_extract 보조 작업이 요약을 담당합니다. 기본값(auxiliary.web_extract.provider: "auto")에서는 주 채팅 모델을 그대로 사용합니다. 즉, hermes model에서 선택한 것과 같은 제공자와 같은 모델입니다. 대부분의 환경에서는 괜찮지만, 고가 추론 모델(Opus, MiniMax M2.7 등)을 주 모델로 쓰는 경우 긴 페이지를 추출할 때마다 비용이 크게 늘 수 있습니다.

주 모델과 관계없이 추출 요약을 저렴하고 빠른 모델로 전달하려면:

# ~/.hermes/config.yaml
auxiliary:
  web_extract:
    provider: openrouter
    model: google/gemini-3-flash-preview
    timeout: 360       # seconds; raise if you hit summarization timeouts

또는 대화형으로 선택: hermes model → 보조 모델 구성 → web_extract.

전체 참조 및 작업별 재정의 패턴은 보조 모델을 참조하세요.

요약이 방해가 될 때

원시 요약되지 않은 페이지 내용을 특별히 필요로 하는 경우 — 예를 들어, LLM 요약이 중요한 필드를 누락할 수 있는 구조화된 페이지를 스크래핑하는 경우 — 대신 browser_navigate + browser_snapshot 를 사용하세요. 브라우저 도구는 보조 모델 재작성 없이 실시간 접근성 트리를 반환합니다(대규모 페이지의 경우 자체 8,000자 스냅샷 제한 적용).

---

설정

hermes tools을 통한 빠른 설정

hermes tools을 실행하고, 웹 검색 및 추출로 이동한 다음 제공자를 선택하세요. 마법사가 필요한 URL이나 API 키를 요청하고 이를 구성에 작성합니다.

hermes tools

---

파이어크롤(기본)

전체 기능 검색, 추출 및 크롤링. 대부분의 사용자에게 권장됩니다.

# ~/.hermes/.env
FIRECRAWL_API_KEY=fc-your-key-here

firecrawl.dev에서 키를 받으세요. 무료 요금제에는 월 500크레딧이 포함되어 있습니다.

셀프 호스팅된 Firecrawl: 클라우드 API 대신 자신의 인스턴스를 가리키세요:

# ~/.hermes/.env
FIRECRAWL_API_URL=http://localhost:3002

FIRECRAWL_API_URL가 설정되면 API 키는 선택 사항입니다 (USE_DB_AUTHENTICATION=false로 서버 인증 비활성화).

---

SearXNG (무료, 자체 호스팅)

SearXNG는 70개 이상의 검색 엔진에서 결과를 집계하는 개인 정보 보호를 중시하는 오픈 소스 메타 검색 엔진입니다. API 키 필요 없음 — Hermes를 실행 중인 SearXNG 인스턴스로 지정하기만 하면 됩니다.

SearXNG는 검색 전용입니다 — web_extract (크롤링 모드를 포함하여) 별도의 추출 제공자가 필요합니다.

옵션 A — Docker로 자체 호스팅 (권장)

이 방법은 속도 제한이 없는 개인 인스턴스를 제공합니다.

1. 작업 디렉토리 생성:

mkdir -p ~/searxng/searxng
cd ~/searxng

2. docker-compose.yml를 작성하세요:

# ~/searxng/docker-compose.yml
services:
  searxng:
    image: searxng/searxng:latest
    container_name: searxng
    ports:
      - "8888:8080"
    volumes:
      - ./searxng:/etc/searxng:rw
    environment:
      - SEARXNG_BASE_URL=http://localhost:8888/
    restart: unless-stopped

3. 컨테이너 시작:

docker compose up -d

4. JSON API 형식 활성화:

SearXNG는 기본적으로 JSON 출력이 비활성화된 상태로 제공됩니다. 생성된 설정을 복사하고 활성화하세요:

# Copy the auto-generated config out of the container
docker cp searxng:/etc/searxng/settings.yml ~/searxng/searxng/settings.yml

~/searxng/searxng/settings.yml를 열고 formats 블록(약 84번째 줄)을 찾으세요:

# Before (default — JSON disabled):
formats:
  - html

# After (enable JSON for Hermes):
formats:
  - html
  - json

5. 적용하려면 다시 시작:

docker cp ~/searxng/searxng/settings.yml searxng:/etc/searxng/settings.yml
docker restart searxng

6. 작동하는지 확인:

curl -s "http://localhost:8888/search?q=test&format=json" | python3 -c \
  "import sys,json; d=json.load(sys.stdin); print(f'{len(d[\"results\"])} results')"

10 results와 비슷한 출력이 보여야 합니다. 403 Forbidden이 반환되면 JSON 형식이 아직 비활성화된 것이므로 4단계를 다시 확인하세요.

7. Hermes 구성:

# ~/.hermes/.env
SEARXNG_URL=http://localhost:8888

그런 다음 ~/.hermes/config.yaml에서 검색 백엔드로 SearXNG를 선택하세요:

web:
  search_backend: "searxng"

또는 hermes tools → 웹 검색 및 추출 → SearXNG를 통해 설정하세요.

---

옵션 B — 공용 인스턴스 사용

공용 SearXNG 인스턴스는 searx.space에 나열되어 있습니다. JSON 형식이 활성화된 인스턴스로 필터링하세요(테이블에 표시됨).

# ~/.hermes/.env
SEARXNG_URL=https://searx.example.com

Public instances

공용 인스턴스는 속도 제한이 있고, 가동 시간이 일정하지 않으며, 언제든지 JSON 형식을 비활성화할 수 있습니다. 프로덕션 환경에서는 자체 호스팅을 강력히 권장합니다.

---

SearXNG를 추출 제공자와 연동하기

SearXNG는 검색을 처리합니다; web_extract(모든 딥 크롤 모드 포함)을 위해서는 별도의 제공자가 필요합니다. 각 기능별 키를 사용하세요:

# ~/.hermes/config.yaml
web:
  search_backend: "searxng"
  extract_backend: "firecrawl"   # or tavily, exa, parallel

이 구성으로, Hermes는 모든 검색 쿼리에 SearXNG를 사용하고 URL 추출에는 Firecrawl을 사용합니다 — 무료 검색과 고품질 추출을 결합합니다.

---

타빌리

관대한 무료 요금제로 AI 최적화 검색, 추출 및 크롤링.

# ~/.hermes/.env
TAVILY_API_KEY=tvly-your-key-here

app.tavily.com에서 키를 받으세요. 무료 요금제에는 한 달에 1,000회 검색이 포함됩니다.

---

엑사

의미 이해를 통한 신경망 검색. 연구와 개념적으로 관련된 콘텐츠를 찾는 데 좋습니다.

# ~/.hermes/.env
EXA_API_KEY=your-exa-key-here

exa.ai에서 키를 받으세요. 무료 요금제에는 월 1,000회 검색이 포함되어 있습니다.

---

평행

심층 연구 기능을 갖춘 AI 기반 검색 및 추출.

# ~/.hermes/.env
PARALLEL_API_KEY=your-parallel-key-here

parallel.ai에서 액세스하세요.

---

구성

단일 백엔드

모든 웹 기능에 대해 하나의 제공자를 설정하세요:

# ~/.hermes/config.yaml
web:
  backend: "searxng"   # firecrawl | searxng | tavily | exa | parallel

기능별 구성

검색과 추출에 서로 다른 제공자를 사용하세요. 이렇게 하면 무료 검색(SearXNG)을 유료 추출 제공자와 결합하거나 그 반대로도 가능합니다:

# ~/.hermes/config.yaml
web:
  search_backend: "searxng"     # used by web_search
  extract_backend: "firecrawl"  # used by web_extract (and its deep-crawl modes)

개별 기능 키가 비어 있을 때, 둘 다 web.backend로 넘어갑니다. web.backend도 비어 있는 경우, 백엔드는 존재하는 API 키/URL에서 자동으로 감지됩니다.

우선 순위 (기능별):

1. web.search_backend / web.extract_backend (능력별 명시적)
2. web.backend (공유 대체)
3. 환경 변수에서 자동 감지

자동 감지

명시적으로 백엔드가 구성되지 않은 경우, Hermes는 설정된 자격 증명에 따라 사용 가능한 첫 번째 백엔드를 선택합니다:

자격 증명 있음	자동 선택된 백엔드
FIRECRAWL_API_KEY 또는 FIRECRAWL_API_URL	불기어가기
PARALLEL_API_KEY	평행
TAVILY_API_KEY	타빌리
EXA_API_KEY	예시
SEARXNG_URL	searxng

---

설정을 확인하세요

어떤 웹 백엔드가 감지되었는지 확인하려면 hermes setup 을 실행하세요:

✅ Web Search & Extract (searxng)

또는 CLI를 통해 확인하세요:

# Activate the venv and run the web tools module directly
source ~/.hermes/hermes-agent/.venv/bin/activate
python -m tools.web_tools

활성 백엔드와 상태가 출력됩니다:

✅ Web backend: searxng
   Using SearXNG (search only): http://localhost:8888

---

문제 해결

web_search 가 {"success": false} 을 반환합니다

• SEARXNG_URL에 접근할 수 있는지 확인: curl -s "http://localhost:8888/search?q=test&format=json"
• HTTP 403 오류가 발생하면 JSON 형식이 비활성화된 것입니다 — settings.yml에서 formats 목록에 json을 추가하고 재시작하세요
• 연결 오류가 발생하면 컨테이너가 실행 중이 아닐 수 있습니다: docker ps | grep searxng

web_extract가 '검색 전용 백엔드'라고 말합니다

SearXNG는 URL 콘텐츠를 추출할 수 없습니다. 추출을 지원하는 제공자에 web.extract_backend를 설정하세요:

web:
  search_backend: "searxng"
  extract_backend: "firecrawl"  # or tavily / exa / parallel

SearXNG가 0개의 결과를 반환했습니다

일부 공개 인스턴스에서는 특정 검색 엔진이나 카테고리를 비활성화합니다. 시도해 보세요:

• 다른 문의
• searx.space와 다른 공개 인스턴스
• 신뢰할 수 있는 결과를 위해 자신의 인스턴스를 직접 호스팅하기

공용 인스턴스에서 속도 제한됨

자가 호스팅 인스턴스로 전환하세요 (옵션 A 참조). Docker를 사용하면, 자신의 인스턴스에는 속도 제한이 없습니다.

web_extract은 '요약 시간 초과' 메모와 함께 잘린 콘텐츠를 반환합니다

보조 모델이 설정된 시간 내에 요약을 완료하지 못했습니다. 다음 중 하나일 수 있습니다:

• config.yaml에서 auxiliary.web_extract.timeout를 올리세요 (새 설치 시 기본값 360초, 키가 없으면 30초)
• web_extract 보조 작업을 더 빠른 모델(예: google/gemini-3-flash-preview)로 전환하세요 — web_extract가 긴 페이지를 처리하는 방법을 참조하세요
• 요약이 잘못된 도구인 페이지에서는 대신 browser_navigate를 사용하세요

---

선택 가능한 기술: searxng-search

웹 도구 세트가 사용 불가능할 때 백업 용도로 curl 를 통해 직접 SearXNG를 사용해야 하는 에이전트의 경우, searxng-search 선택적 스킬을 설치하세요:

hermes skills install official/research/searxng-search

이는 에이전트에게 다음을 가르치는 스킬을 추가합니다:

• curl 또는 Python을 통해 SearXNG JSON API를 호출하세요
• 카테고리별 필터 (general, news, science, 등)
• 페이지 매김 및 오류 사례 처리
• SearXNG에 접근할 수 없을 때 우아하게 대체 동작을 수행하세요