웹 검색 및 추출

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-free-self-hosted}

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

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

#### 옵션 A — Docker로 자체 호스팅 (권장) \{#option-a--self-host-with-docker-recommended}

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

**1. 작업 디렉토리 생성:**

```bash
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번째 줄)을 찾으세요:

```yaml
# 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/.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에 접근할 수 없을 때 우아하게 대체 동작을 수행하세요