> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.beatapi.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.beatapi.io/_mcp/server.

# AnythingLLM에서 BeatAPI 사용하기

> AnythingLLM 워크스페이스의 채팅 모델로 BeatAPI를 사용하고, 문서와 임베딩은 로컬에 둡니다.

# AnythingLLM에서 BeatAPI 사용하기

AnythingLLM은 내 문서로 비공개 지식 베이스를 만들고 그 문서를 바탕으로 질문에 답합니다. BeatAPI는 **Generic OpenAI** 제공자를 통해 채팅 모델을 제공하며, 문서와 벡터 인덱스는 AnythingLLM을 배포한 곳에 그대로 남습니다.

## 사전 준비

1. **AnythingLLM 설치** — Windows, macOS, Linux용 데스크톱 버전 또는 Docker 배포.
2. **BeatAPI API 키** — [대시보드 → API Keys](https://beatapi.io/dashboard/apikeys)에서 만드세요.

## 1단계: LLM 설정 열기

AnythingLLM을 실행하고 왼쪽 아래의 **Open settings**를 클릭한 다음 왼쪽 메뉴에서 **LLM Preference**를 클릭하세요.

## 2단계: BeatAPI 설정

LLM Provider로 **Generic OpenAI**를 선택하고 다음을 입력하세요.

| 필드         | 값                           |
| ---------- | --------------------------- |
| API Key    | BeatAPI API 키               |
| Base URL   | `https://api.beatapi.io/v1` |
| Chat Model | 모델 ID(예: `claude-sonnet-5`) |

> **Note**
>
> 여기서 Base URL에는 `/v1`을 **포함**하고 그 뒤에는 아무것도 붙이지 마세요. AnythingLLM이 `/chat/completions`를 덧붙입니다.

**Save**를 클릭하세요. AnythingLLM이 연결을 테스트하고 결과를 알려 줍니다.

| 모델 ID              | 추천 용도                     |
| ------------------ | ------------------------- |
| `claude-sonnet-5`  | 문서 Q\&A에서 품질과 비용의 균형      |
| `claude-fable-5-1` | 까다로운 종합 작업을 위한 최신 세대      |
| `gpt-5.6-terra`    | 강력한 범용 대안                 |
| `gemini-3.7-flash` | 대량 문서에서 빠르고 저렴하게          |
| `glm-5.3-flash`    | 질의량이 많을 때 가장 저렴한 등급       |
| `kimi-k3`          | 긴 컨텍스트. 검색 결과 청크가 많을 때 유용 |

전체 목록은 [텍스트 API](/text-api) 페이지와 [가격 페이지](https://beatapi.io/pricing)에 있습니다.

## 3단계: 임베딩 모델 선택

> **Note**
>
> **BeatAPI는 임베딩 엔드포인트를 제공하지 않습니다.** Embedding Provider는 AnythingLLM 내장 임베더로 두거나 임베딩을 제공하는 서비스를 지정하세요. Embedding Preference에서 BeatAPI 기본 URL로 **Generic OpenAI**를 설정하면 `/v1/embeddings`가 공개 API에 없으므로 실패합니다.

AnythingLLM에는 같은 머신에서 실행되고 키가 필요 없는 로컬 임베더가 포함되어 있습니다. 비공개 지식 베이스라면 대개 이쪽이 더 낫습니다. 문서 원문은 배포 환경 밖으로 나가지 않고, 검색된 발췌문만 채팅 모델로 전송됩니다.

## 4단계: 워크스페이스를 만들고 문서 추가

1. **+ New Workspace**를 클릭하고 이름을 입력하세요.
2. **Upload Documents**를 클릭해 파일을 추가하거나 끌어다 놓으세요.
3. 처리가 끝날 때까지 기다리세요. 문서는 로컬에서 청크로 나뉘고 임베딩됩니다.

지원되는 입력으로는 `.txt`, `.md`, `.pdf`, `.docx`, 소스 파일, `.csv`, `.json`, URL로 가져온 페이지가 있습니다.

## 5단계: 질문하기

워크스페이스에 질문을 입력하세요. AnythingLLM이 문서에서 관련 청크를 찾아 질문과 함께 BeatAPI 모델로 보냅니다.

워크스페이스마다 문서, 시스템 프롬프트, 대화 기록이 따로 있으므로 배포 하나로 서로 관련 없는 지식 베이스 여러 개를 운영할 수 있습니다.

## 자주 묻는 질문

### AnythingLLM이 연결되지 않음

1. Base URL은 `/v1`을 포함한 `https://api.beatapi.io/v1`여야 하며, 끝에 슬래시를 붙이지 않습니다.
2. [대시보드 → API Keys](https://beatapi.io/dashboard/apikeys)에서 키가 활성 상태인지 확인하세요.
3. Docker 배포라면 컨테이너 자체가 `api.beatapi.io`에 접근할 수 있는지 확인하세요. 데스크톱에서 테스트에 성공해도 컨테이너 네트워크 상태는 알 수 없습니다.

### 임베딩 설정이 실패함

예상된 동작입니다. 3단계를 참고하세요. BeatAPI는 채팅만 제공하며 임베딩은 제공하지 않습니다. 내장 임베더를 사용하세요.

### 검색 결과가 쓸모없음

모델이 아니라 검색 쪽 문제입니다. 문서가 제대로 파싱되었는지 확인한 뒤 다시 업로드하거나, 유사도 임계값을 낮추거나, 워크스페이스 설정에서 반환할 청크 수를 늘리세요. 검색 결과가 비어 있으면 채팅 모델을 바꿔도 해결되지 않습니다.

### 답변이 느림

더 빠른 등급(`gemini-3.7-flash` 또는 `glm-5.3-flash`)으로 바꾸고 질문당 검색하는 청크 수를 줄이세요. 검색 크기가 입력 토큰 수를 직접 좌우합니다.

### 402 insufficient_credits

잔액 부족: 잔액이 0이거나 요청 가격보다 적습니다. 대시보드에서 충전하세요.

### 사용량과 지출 확인

대시보드에서 API 키별 호출 수, 토큰, 비용을 볼 수 있으며, [`GET /v1/usage`](/quick-guide)에서도 같은 수치를 받을 수 있습니다. AnythingLLM 전용 키를 따로 만들면 사용량을 다른 용도와 구분할 수 있습니다.

## 지원

[대시보드](https://beatapi.io/dashboard)에서 지원 티켓을 열고 실패한 응답의 `request_id`를 함께 보내 주세요.