第一个请求
启动服务、添加提供商,用任意协议发出第一条请求
本页带你走通最小闭环:启动服务 → 添加提供商 → 发请求 → 看日志。控制台里每一步的截图见管理控制台。
1. 启动服务
命令bash
默认后台运行,监听 127.0.0.1:17321。常用变体:
命令bash
确认状态:
命令bash
2. 添加一个提供商
打开控制台(astra open,或桌面端直接启动),进入 提供商 页:
- 点击右上角 添加提供商;
- 从模板中选择服务商(Anthropic / OpenAI / DeepSeek / OpenRouter…,或「自定义提供商」接入任意兼容接口);
- 填入 API Key(加密保存在本机
~/.astra/keys),保存; - 点 测试连接 打开测试弹窗,点「开始测试」,显示「测试成功」与耗时即可。
详细截图:提供商页教程。
3. 发出请求
网关的每个请求都要带一个令牌。首次启动时 Astra 会自动生成「默认令牌」:在控制台的 令牌 页点它的 设置,在 提供商池 里添加刚才的提供商,再点复制按钮拿到令牌(形如 sk-astra-…)。
网关对三种主流协议都开放了兼容端点,把 base URL 指向 Astra、带上令牌即可:
命令bash
直接使用令牌的请求会发往令牌提供商池里的提供商;请求协议与提供商接口不一致时,Astra 会自动转换。池里只有一个提供商时请求都发给它;加入多个提供商后,可以选择主备、轮询、加权等分配方式,某个提供商限流或出错时自动换下一个,见提供商池。没有设置任何提供商的令牌只能通过已启用的客户端使用。
图像生成与编辑
网关也转发 OpenAI 的 Images API,供 gpt-image-1 这类图像模型使用:
命令bash
- 必须带
model:Astra 按模型选择提供商,与对话请求相同(客户端绑定的提供商里第一个提供该模型的,或令牌提供商池按策略选出的成员)。智能路由的虚拟模型astra-auto不能用于图像接口。 - 只发往 OpenAI 兼容的提供商:图像地址是提供商 OpenAI 接口(openai-chat / openai-responses)的基础地址加
/images/generations或/images/edits;接口填的是完整地址时,取/chat/completions或/responses之前的部分(Azure 的?api-version=会保留)。没有 OpenAI 接口的提供商(例如只有 Anthropic 接口)和插件提供商会返回 501。 - 不做协议转换:请求体与响应原样转发(包括
stream: true的事件流),只改写模型映射后的模型名和隐私护栏脱敏的文字;上游的错误也原样返回。edits的表单读到model字段就开始向上游转发,model在图片之前时(OpenAI 的 SDK 和文档都这样发)上传的图片不会在 Astra 里整份缓存;开启了隐私护栏时,Astra 会先读完整个表单、检查其中的文字字段(如prompt)再转发。 - 计费:按响应里的
usage(文本输入、图像输入、图像输出 token)和该模型的价格计算。在模型价格里填「图像输入」「图像输出」单价,没填时按输入、输出单价计;模型没有价格或响应没有usage时费用记 0。 - 请求日志:协议列显示
openai-images。图片本身(b64_json、上传的文件)和提示词不会写入请求日志、链路追踪,开启调试抓包时也不会保存。 - 暂不支持:
/v1/images/variations(只有 dall-e-2 支持)。令牌提供商池只把图像请求发给策略选出的第一个成员,失败时不会换下一个成员重试。
4. 查看结果
- 概览 页出现费用、请求数、token 统计与趋势图;
- 请求日志 页可以点开这条请求,查看逐项计费(输入 / 缓存命中 / 缓存写入 / 输出)、耗时与请求体;
- 如果配置了隐私护栏且命中敏感信息,请求详情会标注「已脱敏 N 处」或「已拦截」。
5. 接管一个客户端(可选但推荐)
与其让客户端直接配 base URL,不如让 Astra 代管:
在 客户端 页点「启用…」,Astra 会把网关地址与令牌写进客户端配置(首次修改前自动备份原文件)。之后切换提供商、切换模型都在控制台完成,客户端无需再动。详见客户端教程。