Astra GateEnglish

第一个请求

启动服务、添加提供商,用任意协议发出第一条请求

本页带你走通最小闭环:启动服务 → 添加提供商 → 发请求 → 看日志。控制台里每一步的截图见管理控制台。

1. 启动服务

命令bash
astra start

默认后台运行,监听 127.0.0.1:17321。常用变体:

命令bash
astra start --open            # 启动后打开控制台
astra start --port 18000      # 换端口
astra start --foreground      # 前台运行(看日志排错)

确认状态:

命令bash
astra status

2. 添加一个提供商

打开控制台(astra open,或桌面端直接启动),进入 提供商 页:

  1. 点击右上角 添加提供商;
  2. 从模板中选择服务商(Anthropic / OpenAI / DeepSeek / OpenRouter…,或「自定义提供商」接入任意兼容接口);
  3. 填入 API Key(加密保存在本机 ~/.astra/keys),保存;
  4. 点 测试连接 打开测试弹窗,点「开始测试」,显示「测试成功」与耗时即可。

详细截图:提供商页教程。

3. 发出请求

网关的每个请求都要带一个令牌。首次启动时 Astra 会自动生成「默认令牌」:在控制台的 令牌 页点它的 设置,在 提供商池 里添加刚才的提供商,再点复制按钮拿到令牌(形如 sk-astra-…)。

网关对三种主流协议都开放了兼容端点,把 base URL 指向 Astra、带上令牌即可:

命令bash
curl http://127.0.0.1:17321/v1/chat/completions \
  -H "Authorization: Bearer sk-astra-你的令牌" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-chat",
    "messages": [{ "role": "user", "content": "你好,Astra" }]
  }'

直接使用令牌的请求会发往令牌提供商池里的提供商;请求协议与提供商接口不一致时,Astra 会自动转换。池里只有一个提供商时请求都发给它;加入多个提供商后,可以选择主备、轮询、加权等分配方式,某个提供商限流或出错时自动换下一个,见提供商池。没有设置任何提供商的令牌只能通过已启用的客户端使用。

图像生成与编辑

网关也转发 OpenAI 的 Images API,供 gpt-image-1 这类图像模型使用:

方法路径请求体
POST/v1/images/generationsJSON(model、prompt 等)
POST/v1/images/editsmultipart/form-data 表单(图片 + model、prompt 等),或引用图片的 JSON
命令bash
curl http://127.0.0.1:17321/v1/images/generations \
  -H "Authorization: Bearer sk-astra-你的令牌" \
  -H "Content-Type: application/json" \
  -d '{ "model": "gpt-image-1", "prompt": "一只读报纸的水彩狐狸", "size": "1024x1024" }'
  • 必须带 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 会把网关地址与令牌写进客户端配置(首次修改前自动备份原文件)。之后切换提供商、切换模型都在控制台完成,客户端无需再动。详见客户端教程。