内容
English | [한국어](README.ko.md)
# 丹波鲁标签映射服务器
一个将韩语自然语言描述映射到真实的丹波鲁标签的MCP服务器，内置幻觉过滤。
**服务器**负责标签搜索和存在验证。**分解、翻译、标签选择和自然语言生成**通过捆绑的`danbooru_workflow`提示委托给客户端LLM（例如Claude）。
## 架构
```
用户（韩语）
│
▼
客户端LLM ←── danbooru_workflow 提示（逐步说明）
（例如Claude）
│ MCP工具调用
▼
MCP服务器（此仓库）
├── 搜索标签 普通标签的向量搜索
├── 搜索角色 角色/版权标签查找
├── 过滤现有 幻觉防护 — 丢弃虚构标签
└── 清理角色标签 移除角色衍生的噪声标签
│
▼
LanceDB（向量索引） + ONNX 多语言-e5-large
```
- **嵌入模型**: `intfloat/multilingual-e5-large` 转换为ONNX（CPU推理；GPU可选，仅用于构建）
- **索引**: 英文标签名 + 每条记录的韩语别名
- **标签数据**: 丹波鲁标签与韩语别名，感谢 [NyanTong](https://arca.live/b/aiart/139793445)
## 自主托管
ONNX模型和LanceDB索引**不随仓库发布** — 您必须在本地构建。CSV文件也不会被重新分发；请直接从作者处下载。
### 前置条件
- Python 3.11+
- [uv](https://github.com/astral-sh/uv)
### 步骤 1 — 获取 CSV
下载NyanTong在arca.live上发布的韩语注释丹波鲁标签CSV：
> <https://arca.live/b/aiart/139793445>
将文件放在项目根目录下，并命名为 **`danbooru-tags.csv`**.
### 步骤 2 — 转换模型并构建索引
```bash
uv pip install -e ".[build]"
python scripts/setup.py # 适用于任何机器（~2小时，取决于硬件）
```
**更快的GPU构建（Windows）：**
```bash
uv pip install onnxruntime-directml
python scripts/setup.py --gpu # （~7分钟在RTX 4060上）
```
如果没有GPU，`--gpu`会自动切换到CPU。
从HuggingFace下载 `intfloat/multilingual-e5-large`，将其转换为ONNX（`models/e5-large-onnx/`），并构建LanceDB索引（`data/lancedb_b/`）。
如果模型或索引已经存在，则会自动跳过这些步骤。可以使用 `--force` 强制重新构建。
<details>
<summary>手动运行单个步骤（高级）</summary>
```bash
# 仅转换模型
python scripts/convert_to_onnx.py
# 仅构建索引 — CPU
python -m danbooru_mcp.core.builder b
# 仅构建索引 — GPU（自动检测DirectML → CUDA → CPU）
python -m danbooru_mcp.core.builder b --gpu
```
</details>
### 步骤 3 — 运行 MCP 服务器
```bash
# 标准输入输出传输（适用于Claude Desktop等MCP客户端）
uv run danbooru-mcp
# HTTP/SSE传输（适用于网络客户端）
uv run danbooru-mcp --http
```
### 步骤 4 — 与客户端注册
该MCP服务器通过 **标准输入输出** 运行，适用于任何兼容MCP的客户端。
将 `/path/to/danbooru-tag-rag-mcp` 替换为仓库的绝对路径。
#### Claude Desktop
在 `claude_desktop_config.json` 中添加：
```json
{
"mcpServers": {
"danbooru-tag-rag": {
"command": "uv",
"args": [
"run",
"--directory", "/path/to/danbooru-tag-rag-mcp",
"danbooru-mcp"
]
}
}
}
```
重启应用；验证工具图标是否出现。
#### Claude Code
```bash
claude mcp add danbooru-tag-rag -- uv run --directory /path/to/danbooru-tag-rag-mcp danbooru-mcp
```
在Claude Code内部运行 `/mcp` 以确认连接。
#### Codex
```bash
codex mcp add danbooru-tag-rag -- uv run --directory /path/to/danbooru-tag-rag-mcp danbooru-mcp
```
在Codex内部运行 `/mcp` 以确认。配置存储在 `~/.codex/config.toml` 中。
如果 `uv` 不在PATH中，请在命令中使用其绝对路径。
### 环境变量（可选）
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `DATA_DIR` | `<repo>/data` | LanceDB 目录 |
| `MODELS_DIR` | `<repo>/models` | ONNX 模型目录 |
| `EMBEDDING_DEVICE` | auto | 推理设备（`cuda` 或 `cpu`） |
| `LLM_API_URL` | `http://localhost:8080/v1/chat/completions` | 本地LLM端点（标准MCP模式下未使用） |
## 已知限制
- 一些仅有英文名称的角色标签可能会出现在普通标签搜索结果中。它们很少是顶部结果，可以手动过滤。
- 某些游戏界面术语（例如弹幕、节奏游戏元素）可能会被归类为版权条目而不是普通标签。
- CSV中缺失的罕见角色将无法被找到。在这些情况下，请直接提供确切的英文丹波鲁标签。
## 鸣谢
**代码**
[joykst96/danbooru-tag-rag](https://github.com/joykst96/danbooru-tag-rag) （MIT License）
搜索和幻觉过滤逻辑源自该项目。MCP接口和架构重新设计是本仓库的新工作。
**标签数据**
韩语丹波鲁标签CSV文件由 **NyanTong** 提供 ([arca.live帖子](https://arca.live/b/aiart/139793445))。
CSV文件 **不被重新分发** — 请直接从上述链接下载。
**许可证**: MIT — 见 [LICENSE](LICENSE)。
