# 给 AI 助手

> llms.txt、整份文档的 Markdown、单页 Markdown 与一键复制——让 AI 编程助手读完文档直接写接入代码。

来源：https://www.scirouter.cn/docs/llms · 更新于 2026-09-23

把 SciRouter 接进你的项目时，可以直接让 AI 编程助手（Claude、ChatGPT、Cursor、Copilot……）读我们的文档来写代码。
这一页说明文档的「给机器读」的几种形态，以及怎么用最省事。

## 三种形态

| 地址 | 内容 | 什么时候用 |
|---|---|---|
| [`/llms.txt`](https://www.scirouter.cn/llms.txt) | 目录：每一页的标题、一句话说明、Markdown 地址 | 能联网的助手，让它按需去读 |
| [`/llms-full.txt`](https://www.scirouter.cn/llms-full.txt) | 全部文档合成一个 Markdown 文件，开头附「接入要点」 | 一次性贴给助手，最常用 |
| `/docs/<页面>.md` | 单页的 Markdown，例如 [`/docs/quickstart.md`](https://www.scirouter.cn/docs/quickstart.md) | 只需要某一页时 |

`llms.txt` 的格式遵循 [llmstxt.org](https://llmstxt.org) 的约定。所有链接都是绝对地址，代码示例里的 base URL 已经填成本站实际的地址。

## 一键复制

- **每一页右上角**有「复制 Markdown」：复制的是这一页的 Markdown 原文，带标题、来源地址与更新日期；
- **文档首页**有「复制全部文档」：等于 `/llms-full.txt` 的内容。

复制之后直接粘进对话框，再说你要做什么。

## 一段好用的开场白

```text
下面是 SciRouter（一个 OpenAI 兼容的科研模型 API）的完整接口文档。
请先读「接入要点」，然后帮我：<在这里写你要实现的功能，例如「给我的 FastAPI 服务加一个调用 bio/protein-72b 的接口，流式返回给前端」>。

要求：
- API Key 从环境变量 SCIROUTER_API_KEY 读，不要写进代码；
- 错误按 error.code 分支，按文档区分该重试和不该重试的；
- 流式请求要处理「没收到 [DONE] 就结束」和错误分片两种失败；
- 不要调用文档里没有的接口。

<把复制的文档粘在这里>
```

最后一条值得留着：助手会默认你在调 OpenAI，顺手用上 Responses API、Assistants 之类我们没有的接口。

## 接入要点

`llms-full.txt` 的开头就是下面这一段。只想让助手快速上手、不想贴整份文档时，贴这一段也够写出一个能用的版本：

- **base URL**：`https://api.scirouter.cn/v1`，OpenAI 兼容。只有四个接口：`GET /models`、`GET /models/{model_id}`、`POST /chat/completions`、`POST /embeddings`；旧的 `/completions`、Responses、图片、语音等接口不存在。
- **认证**：`Authorization: Bearer <API Key>`，只认这一种写法。Key 以 `sk-sr-` 开头；从环境变量（如 `SCIROUTER_API_KEY`）读，不要写进代码，也不要放进浏览器、App 等前端。
- **模型 id**：形如 `厂商/模型名`，以 `GET /models` 的返回为准；那个列表只含当前 Key 能调用的模型。
- **错误**：OpenAI 形状 `{"error": {"message", "type", "code", "param", "request_id", "details"}}`。按小写的 `error.code` 分支，不要按 `message`。
- **该重试的**：429 `rate_limited`、502 `upstream_error`、503 `model_unavailable`、504 `upstream_timeout`、409 `idempotency_conflict`（处理中）——指数退避，遵守 `Retry-After`。其余 4xx 不要重试；另外两种 429（`key_quota_exceeded`、`project_budget_exceeded`）要等到下个月或调额度。
- **流式**：跳过以 `:` 开头的注释行（心跳）；`choices` 可能是空数组；出错时是一个 `{"error": …}` 分片，之后断开；**没收到 `data: [DONE]` 的流一律按失败处理**，哪怕 HTTP 状态是 200。
- **截断**：`finish_reason` 为 `length` 表示回答被 `max_tokens` 截断。`max_tokens` 超过模型或套餐上限会 400（`details.limit` 给出上限），不会被悄悄截短。
- **幂等**：非流式请求带 `Idempotency-Key` 头，网络抖动后用同一个键重试不会重复扣费。
- **报障**：记录响应头 `X-Request-Id`（错误体里也有 `request_id`）。