Protected API

TraceRAG API

客户端入口为 https://smillick.org/api/v1/rag。健康检查公开，问答、知识库列表和统计接口需要网关 Bearer API Key。 rag.smillick.org 是回源地址；客户端请使用统一网关。

返回首页

HTTP 接口

GET /api/v1/rag/health：检查服务就绪状态，无需密钥。

GET /api/v1/rag/collections：列出 PDF 知识库。

GET /api/v1/rag/stats：获取语料与模型统计。

POST /api/v1/rag/ask：提交问题，返回回答、上下文来源和检索耗时。

受保护的接口携带 Authorization: Bearer <网关密钥>；问答请求使用 Content-Type: application/json。

{"query":"解释 Dijkstra 算法的适用条件","collection":"algorithm","include_sources":true}

collection 可省略；include_sources 默认为 false，设为 true 后返回片段预览。

错误与重试

401：检查网关密钥；422：检查问题及检索参数；429：达到限流阈值；503：服务繁忙或网关限流不可用；504：回源超时。

排查时保留响应中的 request_id。429 和 503 响应的 Retry-After 表示建议等待秒数。

MCP 与数据范围

源站提供 MCP 工具，公网 Worker 当前只代理上述 REST 接口。PDF 语料由服务端维护，桌面录播缓存不会自动写入知识库。