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

​
完整链路

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

用户问题
  -> POST /v1/embeddings 生成查询向量
  -> 向量数据库召回候选片段
  -> POST /v1/rerank 对候选片段二次排序
  -> 应用按结果 index 取回原片段和来源
  -> POST /v1/chat/completions 或 POST /v1/responses 生成答案
接口可用性取决于 API Key 分组和当前模型。开始开发前先调用 GET /v1/models，并在模型广场确认嵌入与重排模型的接口类型和价格。

​
平台与应用的责任边界

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

​
第一步：生成文档向量

使用模型广场当前标记为嵌入的模型 ID。input 可以是单个字符串或字符串数组；批量上限和可选维度由所选模型决定。 
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。下面只展示缩短后的结构；实际向量维度由模型决定。 
{
  "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 会在支持的标准响应中一并返回文档内容。 
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 表示该候选与查询的相关程度。 
{
  "results": [
    {
      "index": 1,
      "relevance_score": 0.92,
      "document": {
        "text": "API Key 可以在控制台的令牌管理中创建。"
      }
    }
  ],
  "usage": {
    "prompt_tokens": 36,
    "total_tokens": 36
  }
}
不要把分数写成跨模型通用的固定阈值。先使用自己的代表性问题和文档评估召回率、排序质量与成本，再确定候选数、保留数或阈值。

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

按 Rerank 返回的顺序取回原文和来源，只把用户有权访问、且能放入模型上下文的片段交给生成接口：
  • 使用 Chat Completions 时，把检索结果整理为 messages 中的上下文。
  • 使用 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 会保存向量或提供向量数据库吗？

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

​
继续接入

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