OpenAI 兼容接口

SAG 为每个 Agent 暴露一个 OpenAI Chat Completions 兼容端点。标准客户端可以把 SAG 当作模型调用，同时获得站内同样的检索范围、流式回答与原文引用。

端点

POST /api/v1/openai/{agent_id}/chat/completions
Authorization: Bearer <SAG_JWT>
Content-Type: application/json

这是自托管接口，不是 SAG 项目方提供的公共云 API。Base URL 应指向你自己的 SAG 实例。

非流式请求

curl -s http://localhost:8000/api/v1/openai/<AGENT_ID>/chat/completions \
  -H "Authorization: Bearer <SAG_JWT>" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "user", "content": "这份资料讲了什么？"}
    ]
  }'

响应保持标准 chat.completion 结构，并增加 sag.citations：

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "choices": [
    {
      "index": 0,
      "message": {"role": "assistant", "content": "..."},
      "finish_reason": "stop"
    }
  ],
  "sag": {
    "citations": [
      {"chunk_id": "...", "source_id": "...", "title": "..."}
    ]
  }
}

不了解扩展字段的标准客户端会忽略 sag，不会影响基本兼容性。

流式请求

在请求体中设置 "stream": true，服务会通过 SSE 返回增量 chunks。客户端必须持续消费事件直到结束，而不是等待一个完整 JSON 响应。

{
  "messages": [{"role": "user", "content": "总结检索架构"}],
  "stream": true
}

Agent 与知识范围

URL 中的 agent_id 决定使用哪一个 SAG Agent。该 Agent 保存的信源绑定会成为默认知识范围；如需不同范围，创建或更新独立 Agent，而不是在客户端伪造来源。

回答需要 LLM、Embedding 和已就绪文档。接口可达但模型未配置时，服务会返回结构化错误，而不是无依据生成答案。

客户端配置

多数 OpenAI 兼容客户端需要三个值：

配置	值
Base URL	`http://localhost:8000/api/v1/openai/<AGENT_ID>` 或客户端要求的上一级路径
API Key	当前 SAG JWT
Model	客户端若强制要求可填写任意非空标识，实际 Agent 由 URL 决定

不同 SDK 对 Base URL 的拼接方式不同。最终请求必须准确落到 /chat/completions，可先用 curl 验证再配置客户端。