> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloosphere.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 웹 검색

> AI가 실시간 웹 정보를 검색할 수 있도록 검색 엔진과 웹 로더를 구성합니다.

<Info>관리자 › 설정 › 웹 검색</Info>

AI의 웹 검색 기능을 구성합니다.

* 웹 검색이 활성화되면 에이전트가 실시간 인터넷 정보를 참조하여 답변을 생성할 수 있습니다.

<Frame caption="웹 검색 설정 탭">
  <img src="https://mintcdn.com/cloocus/wnNwxuvCsA-ZOlwp/images/admin/settings-web-search.png?fit=max&auto=format&n=wnNwxuvCsA-ZOlwp&q=85&s=285bceb4290aee877515d1e7b95da925" alt="웹 검색 설정 탭" width="2880" height="1800" data-path="images/admin/settings-web-search.png" />
</Frame>

***

## 일반

| 설정 항목    | 설명                               | 기본값  |
| -------- | -------------------------------- | ---- |
| **웹 검색** | 웹 검색 기능 ON/OFF (일반 섹션 하위 마스터 토글) | 비활성화 |

***

## 검색 엔진 선택

지원되는 웹 검색 엔진 목록입니다.

* 사용할 엔진을 선택하고 해당 엔진의 API 키를 입력합니다.

<Accordion title="지원 검색 엔진 전체 (18종)" icon="magnifying-glass">
  | 엔진               | API 키 필요          | 비고                                                        |
  | ---------------- | ----------------- | --------------------------------------------------------- |
  | **SearXNG**      | 불필요 (Self-hosted) | 프라이버시 중심 메타 검색 엔진. Query URL 입력 필요                        |
  | **Google PSE**   | 필요                | Google Programmable Search Engine. API Key + Engine ID 입력 |
  | **Brave Search** | 필요                | Brave 검색 API                                              |
  | **Kagi**         | 필요                | 프리미엄 검색 엔진                                                |
  | **Mojeek**       | 필요                | 독립 크롤러 기반 검색 엔진                                           |
  | **Bocha**        | 필요                | AI 검색 API                                                 |
  | **Serpstack**    | 필요                | Google 검색 결과 API                                          |
  | **Serper**       | 필요                | Google 검색 결과 API                                          |
  | **Serply**       | 필요                | 검색 결과 API                                                 |
  | **SearchAPI**    | 필요                | 멀티 엔진 검색 API. Engine 선택 가능                                |
  | **SerpAPI**      | 필요                | Google 검색 결과 스크래핑. Engine 선택 가능                           |
  | **DuckDuckGo**   | 불필요               | 무료, 프라이버시 중심                                              |
  | **Tavily**       | 필요                | AI 최적화 검색 API                                             |
  | **Jina**         | 필요                | AI 검색 API                                                 |
  | **Bing**         | 필요                | Microsoft Bing Search V7. Endpoint + Subscription Key 입력  |
  | **Exa**          | 필요                | 시맨틱 검색 API                                                |
  | **Perplexity**   | 필요                | AI 기반 검색                                                  |
  | **Sougou**       | 필요                | 중국 검색 엔진. API sID + SK 입력                                 |
</Accordion>

***

## 검색 세부 설정

<Note>
  아래 검색 세부 설정 항목들은 **웹 검색**이 켜져 있을 때만 표시됩니다.
</Note>

| 설정 항목           | 설명                                              | 기본값  |
| --------------- | ----------------------------------------------- | ---- |
| **검색 결과 수**     | 가져올 검색 결과 개수                                    | `5`  |
| **동시 요청 수**     | 병렬 검색 요청 수                                      | `1`  |
| **도메인 필터 목록**   | 허용/차단할 도메인 목록 (콤마 구분)                           | -    |
| **임베딩 및 검색 우회** | 웹 검색 결과에 대한 임베딩·벡터 검색 단계를 우회하고 원문을 그대로 컨텍스트에 전달 | 비활성화 |
| **프록시 환경 신뢰**   | 요청 시 시스템 프록시 환경 변수를 신뢰하여 사용                     | 비활성화 |

**값 조절 가이드**

* **검색 결과 수** — 높이면 더 넓게 정보를 모아 관련 내용을 놓칠 확률이 줄지만, 컨텍스트 토큰·비용이 늘고 무관한 페이지가 섞여 응답이 느려집니다. 낮추면 핵심만 빠르게 참조하지만 필요한 정보를 놓칠 수 있습니다.
* **동시 요청 수** — 높이면 여러 페이지를 병렬로 가져와 검색이 빨라지지만, 검색 API·대상 사이트의 요청 제한(rate limit)에 걸리거나 차단될 위험이 커집니다. 낮추면 안정적이지만 결과 수집이 느려집니다.

***

## 웹 로더

검색 결과 URL에서 웹 페이지 콘텐츠를 가져오는 엔진입니다.

| 엔진               | 특징                                                                      |
| ---------------- | ----------------------------------------------------------------------- |
| **기본 (Default)** | 단순 HTTP 요청으로 텍스트 추출. **Verify SSL Certificate** 토글로 SSL 인증서 검증 여부 설정 가능 |
| **Playwright**   | JavaScript 렌더링 지원, SPA 페이지 처리 가능. WebSocket URL 및 Timeout 설정            |
| **Firecrawl**    | 고급 웹 크롤링 및 콘텐츠 정제. API Base URL 및 API Key 입력 필요                         |
| **Tavily**       | AI 최적화 콘텐츠 추출. Extract Depth 설정 가능                                      |

<Note>
  JavaScript로 렌더링되는 페이지가 많은 경우 Playwright 또는 Firecrawl을 권장합니다.
  기본 로더는 정적 HTML만 처리합니다.
</Note>

***

## YouTube 로더

YouTube 영상의 자막을 검색 소스로 활용할 수 있습니다.

| 설정 항목         | 설명                                                              |
| ------------- | --------------------------------------------------------------- |
| **언어**        | 자막 가져오기 언어 (콤마 구분, 예: `ko,en`)                                  |
| **Proxy URL** | YouTube 접근 시 사용할 프록시 URL (예: `https://user:password@host:port`) |