---
title: "Mastra 自定义 OpenAI 兼容端点（model url）配置 | BroadRouter"
description: "用一个设置了 id、url 和 apiKey 的 model 对象，在 BroadNet Inference 上运行 Mastra 智能体，并说明模型 ID 为什么要写两遍 broadnet/ 前缀。"
url: https://broadrouter.com/zh/guides/mastra-openai-compatible/
lang: zh-Hans
updated: 2026-11-16
publisher: BroadRouter (a BroadNet site); API by BroadNet Inference, https://inference.broadnet.ai
---

本页由英文原文借助 AI 翻译。[阅读英文原文](https://broadrouter.com/guides/mastra-openai-compatible/)（2026-11-16 更新）。

# 在 BroadNet Inference 上运行 Mastra 智能体

更新于 2026-11-16

在 Mastra Agent 中，把 model 设为一个对象：url 为 https://inference.broadnet.ai/v1，apiKey 取自 BROADNET\_API\_KEY，id 为 broadnet/broadnet/glm-5.3。Mastra 会把 id 的第一段当作服务商名并去掉，所以写两遍前缀后，发给 BroadNet 的才是 broadnet/glm-5.3。自定义 URL 默认使用 chat completions。需要工具时请用 GLM 5.3 或 Qwen3.8 27B。

Mastra 是一个用于 AI 智能体和工作流的 TypeScript 框架。除了内置服务商之外，智能体的 `model` 还可以是任意 OpenAI 兼容端点，写成一个包含 `id` 和 `url` 的对象即可。BroadNet Inference 在 `https://inference.broadnet.ai/v1` 上提供标准的 chat completions，所以可以这样接入，只是模型 ID 有一个坑。BroadRouter 是 BroadNet 自己的网站；本文依据 [Mastra 的模型文档](https://mastra.ai/models)和 @mastra/core 1.83.0。

## 安装

```bash
npm install @mastra/core zod
export BROADNET_API_KEY='your-broadnet-key'
```

## 连接一个智能体

```ts
import { Agent } from "@mastra/core/agent";

const broadnet = (model: string) => ({
  id: `broadnet/${model}`,              // Mastra strips the first segment
  url: "https://inference.broadnet.ai/v1",
  apiKey: process.env.BROADNET_API_KEY,
});

export const assistant = new Agent({
  id: "assistant",
  name: "Assistant",
  instructions: "You are a concise assistant.",
  model: broadnet("broadnet/glm-5.3"),     // sends broadnet/glm-5.3
});

const res = await assistant.generate("Give me three names for a Go linting tool.");
console.log(res.text);
```

### 为什么要写两遍前缀

Mastra 的文档说，写成 `provider/model` 的 `id` 会向远端发送不带服务商的模型名，而 `gateway/provider/model` 会在名称中保留服务商。BroadNet 的 ID 本身就含有斜杠，所以需要用更长的形式。我们的测试结果：

| Mastra `id` | BroadNet 收到的模型 ID |
| --- | --- |
| `broadnet/glm-5.3` | `glm-5.3`（错误） |
| `broadnet/broadnet/glm-5.3` | `broadnet/glm-5.3`（正确） |

上面的辅助函数会自动帮你加上多出来的那一段。

## 工具

```ts
import { createTool } from "@mastra/core/tools";
import { z } from "zod";

const weather = createTool({
  id: "get_weather",
  description: "Get the weather for a city",
  inputSchema: z.object({ city: z.string() }),
  execute: async (input) => ({ city: input.city, tempC: 21 }),
});

const agent = new Agent({
  id: "weather",
  name: "Weather",
  instructions: "Use the weather tool to answer.",
  tools: { weather },
  model: broadnet("broadnet/glm-5.3"),
});
```

带工具的智能体请使用 `broadnet/glm-5.3` 或 `broadnet/qwen3.8-27b`。BroadNet 的文档只为这两个模型列出了工具和结构化输出。

## 流式输出

```ts
const stream = await assistant.stream("Explain vector search in two sentences.");
for await (const chunk of stream.textStream) process.stdout.write(chunk);
```

## 需要注意的设置

-   **`url`** 是 base URL，以 `/v1` 结尾。Mastra 会拼上 `/chat/completions`。
-   **不要加 `api: "responses"`。** Mastra 的文档说，这会切换到 `/v1/responses`。BroadNet 没有列出 Responses API。
-   **输出上限。** DeepSeek V4.1 Flash、GLM 5.3 和 Qwen3.8 27B 会先思考再回答，思考内容计入输出上限。如果你限制了输出 token，至少留出 2,000。

## 选哪个模型

| 智能体 | 模型 |
| --- | --- |
| 工具、结构化输出、工作流 | `broadnet/glm-5.3` |
| 工具加图片输入或阿拉伯语文本 | `broadnet/qwen3.8-27b` |
| 固定价格套餐上的纯文本步骤 | `broadnet/deepseek-v4.1-flash` |

[所有模型的价格](https://broadrouter.com/zh/pricing/)。如果不用 Mastra、直接用 Vercel AI SDK，请看 [AI SDK 指南](https://broadrouter.com/zh/guides/vercel-ai-sdk-openai-compatible/)。

## 我们是怎么测试的

2026-11-15，我们在 Node 24 下安装了 @mastra/core 1.83.0，把 `generate`、`stream` 和一个工具智能体指向一个本地 mock 服务器运行。该服务器模拟 BroadNet 的 chat completions 格式，并返回工具调用。我们查看了记录下来的请求：每次调用都发到了 `/v1/chat/completions`，并带有来自 `apiKey` 的 Bearer 密钥。上表中的前缀规则就是这样发现的。我们没有 BroadNet 密钥，因此没有测试真实的模型输出。

## 故障排查

-   **404 或找不到模型。** 模型 ID 很可能丢了前缀。把 `id` 写成 `broadnet/broadnet/glm-5.3`。然后检查 `url` 是否以 `/v1` 结尾。付费模型需要先充值；$5 初始额度只覆盖 `broadnet/gemma-4-26b-a4b` 和两个 Transcribe 模型。
-   **401。** 进程中没有设置 `BROADNET_API_KEY`，或者密钥错误、额度已用完。
-   **回复为空。** 输出预算被思考用光了。[为什么回答会是空的](https://broadrouter.com/zh/guides/reasoning-tokens-empty-response/)。
-   **含并行步骤的工作流出现 429。** 按量付费密钥每分钟允许 30 个请求，同时最多 4 个进行中的请求；套餐会话一次只处理一个。参见[错误码与重试](https://broadrouter.com/zh/guides/errors-and-retries/)。

## 本指南涉及的术语

[AI 智能体（AI agent）](https://broadrouter.com/zh/glossary/agent/)

AI 智能体是由语言模型自主决定步骤、朝目标推进的系统：它决定调用哪些工具、读取结果，然后重复，直到给出最终回答或触及上限。在固定位置调用模型的固定脚本，通常称为工作流（workflow）。

[按量付费（pay-as-you-go）](https://broadrouter.com/zh/glossary/pay-as-you-go/)

按量付费是一种计价模式：你只为实际用量付费，按 token、请求次数或音频分钟等单位计量，没有订阅费，也没有最低消费承诺。大多数大模型 API 都这样计费，从预付余额中扣减或定期开具账单。

[结构化输出（structured output）](https://broadrouter.com/zh/glossary/structured-output/)

结构化输出是大模型 API 的一项功能，它把模型的回复约束为开发者指定的格式（通常是 JSON Schema），让代码能可靠地解析。它比 JSON mode 更严格：JSON mode 只保证输出是合法 JSON，不保证特定结构。

[Base URL（base\_url）](https://broadrouter.com/zh/glossary/base-url/)

base URL 是 API 固定的根地址，例如 https://api.example.com/v1，客户端会把它加在每个端点路径（例如 /chat/completions）前面。在 OpenAI 兼容 SDK 中，修改 base URL，再配合 API 密钥和模型 ID，就能让同一份代码改用另一家服务商。

[Chat Completions API（对话补全接口）](https://broadrouter.com/zh/glossary/chat-completions-api/)

Chat Completions API 是 OpenAI 的 HTTP 端点 POST /v1/chat/completions，它接收模型名称和一组带角色标记的消息，返回模型的下一条消息。它的请求与响应结构已成为 OpenAI 兼容服务商和各类 SDK 通用的格式。

[并发（concurrency）](https://broadrouter.com/zh/glossary/concurrency/)

并发（concurrency）是客户端在同一时刻正在进行中的请求数。大模型 API 往往按密钥或套餐单独限制并发，与每分钟请求数分开计算，因为每个未完成的请求在响应结束前都会占用 GPU 资源。

[大模型包月套餐（flat-rate LLM plan）](https://broadrouter.com/zh/glossary/flat-rate-llm-plan/)

大模型包月套餐（固定价格套餐）是按一个周期（如一个月）收取固定费用、提供大模型 API 使用权的计价方式，不按 token 计费。这类套餐通常会限制别的东西，如并发、速度、模型或使用时间窗口，所以限制条件和价格同样重要。

[输入 token 与输出 token](https://broadrouter.com/zh/glossary/input-and-output-tokens/)

输入 token 是语言模型在一次请求中读取的 token，包括系统提示词、对话历史、工具定义和图片。输出 token 是模型生成回复的 token，包括思考内容。大模型 API 通常分别计价，输出一般更贵。

## 常见问题

### 为什么 Mastra 发送的是 glm-5.3 而不是 broadnet/glm-5.3？

Mastra 把模型 id 解析为“服务商/模型”，只发送第一个斜杠之后的部分。在我们的测试中，id 为 broadnet/glm-5.3 时它发送的是 glm-5.3，BroadNet 无法识别。请把 id 写成 broadnet/broadnet/glm-5.3。

### Mastra 的 url 应该填 base URL 还是 chat completions 的完整 URL？

填 base URL。Mastra 的文档说要使用 OpenAI 兼容端点的 base URL，所以请填 https://inference.broadnet.ai/v1，不带 /chat/completions。

### 使用自定义 URL 时，Mastra 会用 Responses API 吗？

默认不会。Mastra 的文档说，除非你加上 api 设为 responses，否则自定义端点使用 chat completions。BroadNet 提供的是 chat completions，所以不要加。

### Mastra 的工具能在 BroadNet 上用吗？

可以，前提是使用 BroadNet 列出了工具的模型：GLM 5.3 或 Qwen3.8 27B。在我们的 mock 测试中，智能体发送了工具 schema，执行了工具并返回了结果。

## 相关指南

-   [用 Vercel AI SDK 调用 BroadNet Inference](https://broadrouter.com/zh/guides/vercel-ai-sdk-openai-compatible/)
-   [用 OpenAI Node.js SDK 调用 BroadNet Inference](https://broadrouter.com/zh/guides/openai-node-sdk/)
-   [推理模型为什么返回空回答](https://broadrouter.com/zh/guides/reasoning-tokens-empty-response/)
-   [BroadNet Inference 错误码，以及什么时候该重试](https://broadrouter.com/zh/guides/errors-and-retries/)
-   [所有可与 BroadNet Inference 配合使用的工具（英文）](https://broadrouter.com/integrations/)：SDK、编程智能体、聊天界面和自动化工具，并附每个工具的具体设置

用你的真实业务负载试一试。新账户可获得 US$5 初始额度，用于 Gemma和转写。DeepSeek、GLM和Qwen3.8 需要先充值。

[开始使用](https://inference.broadnet.ai/account/?utm_source=broadrouter&utm_medium=referral&utm_campaign=zh-guides-mastra-openai-compatible&utm_content=page-cta) ·

**来源**

-   [Mastra 文档：Models（自定义 OpenAI 兼容端点）（核对于 2026-11-15）](https://mastra.ai/models)
-   [Mastra GitHub：@mastra/core 1.83.0 版本发布，2026-11-13（核对于 2026-11-15）](https://github.com/mastra-ai/mastra/releases/tag/%40mastra%2Fcore%401.83.0)
-   [BroadNet Inference API 参考文档（核对于 2026-11-15）（英文）](https://inference.broadnet.ai/docs?utm_source=broadrouter&utm_medium=referral&utm_campaign=zh-guides-mastra-openai-compatible&utm_content=sources)
