# Embedding（文本向量化）接口 · 实测

> 实测可用：**2026-06-17**。用途：「作用域定位」(scope-link)——把 5 棵分类树节点 + 提取出的候选作用域值向量化，做余弦最近邻对齐（对得上复用现有节点原名、对不上新建）。

## 服务
- 提供方：**火山方舟（Volcengine Ark）**
- 模型：**Doubao-embedding-vision**（多模态向量化，支持文本 / 图片；本项目只用文本）
- 接入方式：预置推理接入点（用 **ep-id** 调用，系统自动匹配预置服务）

## 调用契约

| 项 | 值 |
|---|---|
| Endpoint | `POST https://ark.cn-beijing.volces.com/api/v3/embeddings/multimodal` |
| Auth | `Authorization: Bearer <ARK_API_KEY>`（密钥存 `.env`，**不入库 / 不入文档**） |
| `model` | `ep-20260617180207-vmwg6` |
| 输入 | `{"model":"ep-...","input":[{"type":"text","text":"<文本>"}]}` |
| 输出 | `data.embedding` = 长度 **2048** 的浮点向量 |

请求示例：
```bash
curl https://ark.cn-beijing.volces.com/api/v3/embeddings/multimodal \
  -H "Authorization: Bearer $ARK_API_KEY" -H "Content-Type: application/json" \
  -d '{"model":"ep-20260617180207-vmwg6","input":[{"type":"text","text":"撕裂共识"}]}'
```

## 关键坑（实测）
- **vision 版必须走 `/embeddings/multimodal`**；标准 `/api/v3/embeddings`（input 为字符串数组）会返回 `InvalidParameter`。
- 多模态接口是**单条调用**（一次请求 = 一个向量），批量需多次请求（可并发）。
- 火山方舟用「**预置推理接入点**」即可（用模型 ID / ep-id 直接调，无需自建模型接入点）；模型必须先在该 key 所属**项目**开通。
- 图片向量化：把 input 项换成 `{"type":"image_url","image_url":{"url":"<url 或 data url>"}}`（同一接口，本项目暂不用）。

## env（密钥放 .env，gitignore）
```
ARK_API_KEY=<火山方舟 API Key>
ARK_EMBEDDING_EP=ep-20260617180207-vmwg6
ARK_EMBEDDING_URL=https://ark.cn-beijing.volces.com/api/v3/embeddings/multimodal
ARK_EMBEDDING_DIM=2048
```

## 在本项目的用途
`scope-link`：① 一次性把 global_category（5 棵树 ~5000 节点）的节点名向量化、缓存成本地 `.npy`；② 提取出候选作用域值时即时向量化 → 与缓存做余弦最近邻 → 取 top-K 交模型判定「对齐现有 or 新建」。规模小（~20MB），**内存 + numpy 暴力最近邻即可，无需向量数据库**。
