---
title: RAG 检索接入：Embeddings 与 Rerank
description: 使用无限星河AI的 Embeddings 与 Rerank 接口搭建 RAG 检索链路，完成文档向量化、候选召回、重排序和生成前上下文组装。
lastUpdated: 2026-08-04
---

一条最小 RAG（检索增强生成）链路通常分为两段：先把文档切片并生成向量，查询时再召回候选片段、进行重排序，最后把经过筛选的上下文交给对话模型。无限星河AI提供 Embeddings、Rerank 和生成接口；文档切片、向量存储、租户权限与检索策略由您的应用负责。

## 完整链路

```text
原始文档
  -> 应用切片并保存文档 ID / 来源 / 权限元数据
  -> POST /v1/embeddings 生成文档向量
  -> 应用写入自己的向量数据库

用户问题
  -> POST /v1/embeddings 生成查询向量
  -> 向量数据库召回候选片段
  -> POST /v1/rerank 对候选片段二次排序
  -> 应用按结果 index 取回原片段和来源
  -> POST /v1/chat/completions 或 POST /v1/responses 生成答案
```

<Warning>
接口可用性取决于 API Key 分组和当前模型。开始开发前先调用 `GET /v1/models`，并在[模型广场](https://infistar.cc/pricing)确认嵌入与重排模型的接口类型和价格。
</Warning>

## 平台与应用的责任边界

| 环节 | 无限星河AI接口负责 | 您的应用负责 |
| --- | --- | --- |
| 文档准备 | 不提供业务文档切片或向量存储能力 | 清洗、切片、去重，保存文档 ID、来源与权限元数据 |
| 向量化 | `/v1/embeddings` 返回每项输入对应的向量与索引 | 选择切片长度、批次大小，保存向量及其元数据 |
| 候选召回 | 不托管向量数据库 | 选择向量库、相似度方法、过滤条件和候选数量 |
| 重排序 | `/v1/rerank` 返回候选项的 `index` 与 `relevance_score` | 用 `index` 映射原候选片段，并决定最终保留数量 |
| 答案生成 | Chat Completions 或 Responses 接收组装后的上下文 | 控制提示词、引用格式、上下文上限和业务权限 |

## 第一步：生成文档向量

使用模型广场当前标记为嵌入的模型 ID。`input` 可以是单个字符串或字符串数组；批量上限和可选维度由所选模型决定。

```bash
curl https://infistar.cc/v1/embeddings \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "EMBEDDING_MODEL_ID",
    "input": [
      "退款申请需要在订单完成前提交。",
      "API Key 可以在控制台的令牌管理中创建。"
    ]
  }'
```

响应中的 `data` 数组包含 `index` 与 `embedding`。下面只展示缩短后的结构；实际向量维度由模型决定。

```json
{
  "data": [
    {
      "index": 0,
      "embedding": [0.012, -0.034]
    }
  ],
  "model": "EMBEDDING_MODEL_ID",
  "usage": {
    "prompt_tokens": 18,
    "total_tokens": 18
  }
}
```

把 `index` 对应的原文、文档 ID、来源 URL、更新时间和权限标签与向量一起保存。查询向量与文档向量应使用同一个嵌入模型；更换模型后，应重新生成已有文档向量，不能把不同模型的向量直接混在同一索引中比较。

## 第二步：召回候选片段

用同一嵌入模型把用户问题转换为查询向量，再到自己的向量数据库中召回候选片段。向量数据库、相似度算法和过滤条件不属于 Infistar API 合同。

候选召回阶段应先应用业务权限和租户过滤，避免无权内容进入后续 Rerank 或生成请求。每个候选项保留稳定 ID，后面才能把重排结果映射回原文和来源。

## 第三步：对候选文档重排序

将用户问题放入 `query`，把候选片段按原顺序放入 `documents`。`top_n` 是希望返回的结果数量，不应超过候选文档数；`return_documents: true` 会在支持的标准响应中一并返回文档内容。

```bash
curl https://infistar.cc/v1/rerank \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "RERANK_MODEL_ID",
    "query": "在哪里创建 API Key？",
    "documents": [
      "退款申请需要在订单完成前提交。",
      "API Key 可以在控制台的令牌管理中创建。",
      "视频任务完成后可以下载结果。"
    ],
    "top_n": 2,
    "return_documents": true
  }'
```

标准响应使用 `results` 数组。`index` 指向本次请求中 `documents` 的原始位置，`relevance_score` 表示该候选与查询的相关程度。

```json
{
  "results": [
    {
      "index": 1,
      "relevance_score": 0.92,
      "document": {
        "text": "API Key 可以在控制台的令牌管理中创建。"
      }
    }
  ],
  "usage": {
    "prompt_tokens": 36,
    "total_tokens": 36
  }
}
```

不要把分数写成跨模型通用的固定阈值。先使用自己的代表性问题和文档评估召回率、排序质量与成本，再确定候选数、保留数或阈值。

## 第四步：组装生成上下文

按 Rerank 返回的顺序取回原文和来源，只把用户有权访问、且能放入模型上下文的片段交给生成接口：

- 使用 [Chat Completions](/api-reference/chat-completions) 时，把检索结果整理为 `messages` 中的上下文。
- 使用 [Responses API](/api-reference/responses-api) 时，把检索结果整理为 `input` 或应用已有的结构化输入。
- 如果答案需要展示来源，由应用同时保存并渲染文档 ID、标题或 URL；模型生成的引用不能替代真实来源映射。

## 上线前检查

1. API Key 只保存在服务端或密钥管理系统，不进入网页、移动端安装包或公开仓库。
2. 文档与查询使用同一嵌入模型和一致的文本预处理方式。
3. 向量召回前已经应用租户和文档权限过滤。
4. Rerank 的 `index` 能稳定映射回原候选片段，不按返回数组位置猜测。
5. 对 401、403、429 与 5xx 分别处理；请求结果不确定时不盲目重复写入业务数据。
6. 使用代表性问题离线评估“只向量召回”与“向量召回 + Rerank”的质量、延迟和费用，再决定是否启用重排。
7. 上线后记录使用的公开模型 ID、接口、请求时间和来源文档 ID，便于复现错误答案和更正内容。

## 常见问题

### RAG 一定需要 Rerank 吗？

不一定。小规模或候选已经很准确的检索可以先只使用 Embeddings。候选较多、语义相近内容较多，或需要提高前几条结果质量时，再用自己的评估集判断 Rerank 是否值得启用。

### Embeddings 和 Rerank 可以使用同一个模型吗？

不能仅凭模型名称推断。它们是两个不同接口类型，应分别从 `GET /v1/models` 与模型广场选择当前可用的嵌入模型和重排模型。

### Infistar 会保存向量或提供向量数据库吗？

本指南涉及的公开接口只负责生成向量、对候选文档重排序和生成答案，不提供业务文档切片、向量数据库或租户权限存储。上述数据由您的应用管理。

## 继续接入

- 了解请求字段：[文本嵌入接口](/api-reference/embeddings)与[文档重排序接口](/api-reference/document-rerank)。
- 检查密钥和权限：[API Key、权限与安全边界](/integration-guides/authentication-permissions)。
- 排查限流与错误：[HTTP 状态码排查](/troubleshooting/http-status-troubleshooting)与[429、速率限制和并发](/troubleshooting/rate-limits-concurrency)。
- 比较其它接口：[API 兼容矩阵与迁移决策](/api-compatibility-matrix)。
- 企业检索与接入评估：[联系与企业合作](/enterprise-developers/enterprise-developers)。

本页不推荐固定模型、向量数据库或相关性阈值，也不承诺未经实际数据评估的检索质量、延迟或成本结果。