> 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

> 用 BeatAPI 作为 AnythingLLM 工作区背后的对话模型，文档与向量索引仍留在本地。

# 在 AnythingLLM 中使用 BeatAPI

AnythingLLM 基于你自己的文档搭建私有知识库并回答问题。BeatAPI 通过它的 **Generic OpenAI** 选项提供对话模型；文档与向量索引仍留在你部署 AnythingLLM 的地方。

## 准备工作

1. **已安装 AnythingLLM** —— Windows、macOS、Linux 桌面版，或 Docker 部署。
2. **一把 BeatAPI 密钥** —— 在[控制台 → API 密钥](https://beatapi.io/dashboard/apikeys)创建。

## 第一步：打开模型设置

启动 AnythingLLM，点左下角 **Open settings**，再在左侧菜单选择 **LLM Preference**。

## 第二步：配置 BeatAPI

服务商选 **Generic OpenAI**，然后填写：

| 字段         | 值                           |
| ---------- | --------------------------- |
| API Key    | 你的 BeatAPI 密钥               |
| Base URL   | `https://api.beatapi.io/v1` |
| Chat Model | 模型编号，例如 `claude-sonnet-5`   |

> **Note**
>
> 这里的 Base URL **要带** `/v1`，且后面什么都不加。AnythingLLM 会自己拼上 `/chat/completions`。

点 **Save**，AnythingLLM 会测试连接并给出结果。

| 模型编号               | 适用场景             |
| ------------------ | ---------------- |
| `claude-sonnet-5`  | 文档问答，质量与成本均衡     |
| `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)。

## 第三步：选择嵌入模型

> **Note**
>
> **BeatAPI 不提供 embeddings 接口。** 请把嵌入模型保持为 AnythingLLM 自带的本地嵌入器，或指向其他提供该能力的服务。在 Embedding Preference 里选 **Generic OpenAI** 并填 BeatAPI 地址会失败，因为 `/v1/embeddings` 不在已发布的接口范围内。

AnythingLLM 自带一个跑在本机、不需要密钥的嵌入器。对私有知识库来说这通常反而更合适：文档原文根本不出这台机器，只有检索到的片段才会发给对话模型。

## 第四步：建工作区、传文档

1. 点 **+ New Workspace** 并命名。
2. 点 **Upload Documents** 添加文件，或直接拖入。
3. 等待处理完成 —— 文档会在本地被切片并向量化。

支持的输入包括 `.txt`、`.md`、`.pdf`、`.docx`、源码文件、`.csv`、`.json`，以及按网址抓取的网页。

## 第五步：提问

在工作区里输入问题。AnythingLLM 会从文档中检索相关片段，连同问题一起发给 BeatAPI 上的模型。

每个工作区有独立的文档、独立的系统提示词和独立的历史记录，所以一次部署可以承载多个互不相干的知识库。

## 常见问题

### AnythingLLM 连不上

1. Base URL 必须是 `https://api.beatapi.io/v1` —— 带 `/v1`，结尾不加斜杠。
2. 在[控制台 → API 密钥](https://beatapi.io/dashboard/apikeys)确认密钥仍然可用。
3. Docker 部署的话，要确认**容器本身**能访问 `api.beatapi.io`；在宿主机上测通了并不说明容器也能通。

### 配置嵌入模型时失败

这是预期内的 —— 见第三步。BeatAPI 提供对话，不提供嵌入。请使用自带的本地嵌入器。

### 检索结果没用

这是检索的问题，不是模型的问题。先确认文档解析正确后重新上传，或者在工作区设置里降低相似度阈值、增加返回片段数。换对话模型解决不了检索为空。

### 回答很慢

换成更快的档位 —— `gemini-3.7-flash` 或 `glm-5.3-flash` —— 并减少每次提问检索的片段数。检索量直接决定输入 token 数。

### 402 insufficient_credits

余额不足：余额为零或低于本次请求的价格，在控制台充值。

### 查看用量与消费

控制台按密钥展示调用次数、token 与费用，同样的数据也可从 [`GET /v1/usage`](/quick-guide) 获取。给 AnythingLLM 单独发一把密钥，它的消耗就能和其他用途分开统计。

## 获取支持

在[控制台](https://beatapi.io/dashboard)提交工单，并附上失败响应里的 `request_id`。