---
title: "Mastra với endpoint tương thích OpenAI tùy chỉnh (model url)"
description: "Chạy agent Mastra trên BroadNet Inference bằng một đối tượng model đặt id, url và apiKey, kèm tiền tố broadnet/ lặp đôi mà model ID cần có."
url: https://broadrouter.com/vi/guides/mastra-openai-compatible/
lang: vi
updated: 2026-11-16
publisher: BroadRouter (a BroadNet site); API by BroadNet Inference, https://inference.broadnet.ai
---

Được dịch từ tiếng Anh với sự hỗ trợ của AI. [Đọc bản gốc tiếng Anh](https://broadrouter.com/guides/mastra-openai-compatible/) (cập nhật ngày 2026-11-16).

# Dùng agent Mastra với BroadNet Inference

Cập nhật 2026-11-16

Trong một Agent của Mastra, đặt model là một đối tượng với url https://inference.broadnet.ai/v1, apiKey lấy từ BROADNET\_API\_KEY và id broadnet/broadnet/glm-5.3. Mastra coi phần đầu của id là tên provider và cắt bỏ nó, nên tiền tố lặp đôi giúp gửi broadnet/glm-5.3 tới BroadNet. URL tùy chỉnh mặc định dùng chat completions. Hãy dùng GLM 5.3 hoặc Qwen3.8 27B cho tool.

Mastra là framework TypeScript cho agent và workflow AI. Ngoài các provider tích hợp sẵn, `model` của một agent có thể là bất kỳ endpoint tương thích OpenAI nào, khai báo dưới dạng đối tượng có `id` và `url`. BroadNet Inference phục vụ chat completions chuẩn tại `https://inference.broadnet.ai/v1`, nên kết nối theo cách này được, chỉ có một điểm cần lưu ý ở model ID. BroadRouter là trang web của chính BroadNet; hướng dẫn này dựa trên [tài liệu models của Mastra](https://mastra.ai/models) và @mastra/core 1.83.0.

## Cài đặt

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

## Kết nối một agent

```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);
```

### Vì sao tiền tố phải lặp đôi

Theo tài liệu Mastra, một `id` viết dạng `provider/model` chỉ gửi tên model trần tới phía remote, còn dạng `gateway/provider/model` giữ provider trong tên. ID của BroadNet có chứa dấu gạch chéo, nên cần dạng dài hơn. Trong thử nghiệm của chúng tôi:

| `id` trong Mastra | Model ID mà BroadNet nhận được |
| --- | --- |
| `broadnet/glm-5.3` | `glm-5.3` (sai) |
| `broadnet/broadnet/glm-5.3` | `broadnet/glm-5.3` (đúng) |

Hàm helper ở trên tự thêm đoạn tiền tố này cho bạn.

## Tool

```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"),
});
```

Hãy dùng `broadnet/glm-5.3` hoặc `broadnet/qwen3.8-27b` cho agent có tool. Tài liệu BroadNet chỉ ghi hỗ trợ tool và đầu ra có cấu trúc cho hai model này.

## Streaming

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

## Những cài đặt quan trọng

-   **`url`** là base URL, kết thúc bằng `/v1`. Mastra tự thêm `/chat/completions`.
-   **Đừng thêm `api: "responses"`.** Theo tài liệu Mastra, tùy chọn này chuyển sang `/v1/responses`. BroadNet không liệt kê Responses API.
-   **Giới hạn đầu ra.** DeepSeek V4.1 Flash, GLM 5.3 và Qwen3.8 27B suy luận trước khi trả lời, và phần suy luận được tính vào giới hạn đầu ra. Nếu bạn giới hạn số token đầu ra, hãy để từ 2.000 trở lên.

## Chọn model nào

| Agent | Model |
| --- | --- |
| Tool, đầu ra có cấu trúc, workflow | `broadnet/glm-5.3` |
| Tool kèm đầu vào hình ảnh hoặc văn bản tiếng Ả Rập | `broadnet/qwen3.8-27b` |
| Các bước chỉ có văn bản trên gói giá cố định | `broadnet/deepseek-v4.1-flash` |

[Giá của mọi model](https://broadrouter.com/vi/pricing/). Nếu dùng Vercel AI SDK mà không có Mastra, xem [hướng dẫn AI SDK](https://broadrouter.com/vi/guides/vercel-ai-sdk-openai-compatible/).

## Chúng tôi đã kiểm thử thế nào

Ngày 2026-11-15, chúng tôi cài @mastra/core 1.83.0 với Node 24 và chạy `generate`, `stream` cùng một agent có tool với một mock server cục bộ mô phỏng định dạng chat completions của BroadNet và trả về lệnh gọi tool. Chúng tôi đọc các request được ghi lại. Mọi lệnh gọi đều tới `/v1/chat/completions` với Bearer key lấy từ `apiKey`. Đó cũng là cách chúng tôi phát hiện quy tắc tiền tố trong bảng ở trên. Chúng tôi không có key BroadNet nên chưa kiểm thử đầu ra thật của model.

## Xử lý sự cố

-   **404 hoặc không tìm thấy model.** Nhiều khả năng model ID đã mất tiền tố. Hãy viết `id` là `broadnet/broadnet/glm-5.3`. Sau đó kiểm tra `url` có kết thúc bằng `/v1` không. Các model trả phí cần nạp tiền; với $5 tín dụng ban đầu chỉ dùng được `broadnet/gemma-4-26b-a4b` và hai model Transcribe.
-   **401.** `BROADNET_API_KEY` chưa được đặt trong tiến trình, hoặc key sai hay đã hết hạn mức.
-   **Câu trả lời rỗng.** Phần suy luận đã dùng hết ngân sách đầu ra. [Vì sao câu trả lời trả về rỗng](https://broadrouter.com/vi/guides/reasoning-tokens-empty-response/).
-   **429 trong workflow có các bước song song.** Một key trả theo mức dùng cho phép 30 request mỗi phút và 4 request đang xử lý cùng lúc; một phiên của gói chạy từng request một. Xem [lỗi và thử lại](https://broadrouter.com/vi/guides/errors-and-retries/).

## Thuật ngữ trong hướng dẫn này

[Trả theo mức dùng (pay-as-you-go)](https://broadrouter.com/vi/glossary/pay-as-you-go/)

Trả theo mức dùng (pay-as-you-go) là mô hình giá mà bạn chỉ trả cho những gì đã dùng, đo theo đơn vị như token, request hoặc phút âm thanh, không có gói đăng ký hay cam kết tối thiểu. Hầu hết API LLM tính phí theo cách này, trừ vào số dư trả trước hoặc qua hóa đơn định kỳ.

[Chat Completions API](https://broadrouter.com/vi/glossary/chat-completions-api/)

Chat Completions API là endpoint HTTP của OpenAI, POST /v1/chat/completions, nhận tên model và danh sách message có gắn vai trò rồi trả về message tiếp theo của model. Cấu trúc request và response của nó đã trở thành định dạng chung mà các nhà cung cấp và SDK tương thích OpenAI dùng lại.

[Đầu ra có cấu trúc (structured output)](https://broadrouter.com/vi/glossary/structured-output/)

Đầu ra có cấu trúc (structured output) là tính năng của API LLM buộc câu trả lời của model theo định dạng do lập trình viên chỉ định, thường là JSON Schema, để code parse được tin cậy. Nó chặt hơn JSON mode, vốn chỉ đảm bảo JSON hợp lệ chứ không đảm bảo một cấu trúc cụ thể.

[Giới hạn tần suất (rate limit)](https://broadrouter.com/vi/glossary/rate-limit/)

Giới hạn tần suất (rate limit) là mức trần mà API đặt ra cho lượng sử dụng của một client trong một khoảng thời gian, như số request mỗi phút hoặc số token mỗi phút. Request vượt giới hạn bị từ chối, thường với HTTP 429 Too Many Requests, cho đến khi mức dùng giảm xuống dưới giới hạn.

[Token](https://broadrouter.com/vi/glossary/token/)

Token là đơn vị văn bản mà model ngôn ngữ đọc và viết: một từ, một phần của từ, một dấu câu hoặc một chuỗi byte do tokenizer của model tạo ra. API LLM đếm, giới hạn và thường tính phí theo token.

[API tương thích OpenAI (OpenAI-compatible API)](https://broadrouter.com/vi/glossary/openai-compatible-api/)

API tương thích OpenAI là một HTTP API nhận cùng định dạng request và phản hồi như OpenAI API, ví dụ POST /v1/chat/completions, nên SDK và công cụ của OpenAI dùng được nó chỉ bằng cách đổi base URL, API key và tên model.

[Base URL](https://broadrouter.com/vi/glossary/base-url/)

Base URL là địa chỉ gốc cố định của một API, như https://api.example.com/v1, mà client đặt trước mọi đường dẫn endpoint, như /chat/completions. Trong SDK tương thích OpenAI, đổi base URL cùng với API key và model ID sẽ trỏ cùng một đoạn code sang nhà cung cấp khác.

[Concurrency (request đồng thời)](https://broadrouter.com/vi/glossary/concurrency/)

Concurrency (request đồng thời) là số request mà một client đang xử lý cùng lúc. Các API LLM thường giới hạn nó theo key hoặc theo gói, tách biệt với số request mỗi phút, vì mỗi request đang mở chiếm dụng năng lực GPU cho tới khi response kết thúc.

## Câu hỏi thường gặp

### Vì sao Mastra gửi glm-5.3 thay vì broadnet/glm-5.3?

Mastra đọc id của model theo dạng provider/model và chỉ gửi phần sau dấu gạch chéo đầu tiên. Với id broadnet/glm-5.3, trong thử nghiệm của chúng tôi nó gửi glm-5.3, một ID mà BroadNet không nhận ra. Hãy viết id là broadnet/broadnet/glm-5.3.

### url của Mastra nên là base URL hay URL chat completions?

Base URL. Tài liệu Mastra hướng dẫn dùng base URL của endpoint tương thích OpenAI, nên hãy dùng https://inference.broadnet.ai/v1, không kèm /chat/completions.

### Mastra có dùng Responses API với URL tùy chỉnh không?

Mặc định thì không. Theo tài liệu Mastra, endpoint tùy chỉnh dùng chat completions trừ khi bạn thêm api là responses. Đừng thêm cho BroadNet, vì BroadNet phục vụ chat completions.

### Tool của Mastra có chạy trên BroadNet không?

Có, trên một model BroadNet ghi hỗ trợ tool là GLM 5.3 hoặc Qwen3.8 27B. Trong thử nghiệm với mock server, agent đã gửi schema của tool, chạy tool và trả về kết quả.

## Hướng dẫn liên quan

-   [Dùng Vercel AI SDK với BroadNet Inference](https://broadrouter.com/vi/guides/vercel-ai-sdk-openai-compatible/)
-   [Dùng OpenAI Node.js SDK với BroadNet Inference](https://broadrouter.com/vi/guides/openai-node-sdk/)
-   [Vì sao model suy luận trả về câu trả lời rỗng](https://broadrouter.com/vi/guides/reasoning-tokens-empty-response/)
-   [Mã lỗi BroadNet Inference và khi nào nên thử lại](https://broadrouter.com/vi/guides/errors-and-retries/)
-   [Mọi công cụ dùng được với BroadNet Inference (tiếng Anh)](https://broadrouter.com/integrations/): SDK, agent lập trình, giao diện chat và công cụ tự động hóa, kèm cấu hình chính xác cho từng công cụ

Hãy thử với khối lượng công việc thực tế của bạn. Tài khoản mới được tặng US$5 tín dụng ban đầu cho Gemma và chuyển giọng nói thành văn bản. DeepSeek, GLM và Qwen3.8 cần nạp tiền.

[Bắt đầu](https://inference.broadnet.ai/account/?utm_source=broadrouter&utm_medium=referral&utm_campaign=vi-guides-mastra-openai-compatible&utm_content=page-cta) ·

**Nguồn**

-   [Tài liệu Mastra, Models (endpoint tương thích OpenAI tùy chỉnh) (kiểm tra ngày 2026-11-15)](https://mastra.ai/models)
-   [Mastra trên GitHub, bản phát hành @mastra/core 1.83.0, 2026-11-13 (kiểm tra ngày 2026-11-15)](https://github.com/mastra-ai/mastra/releases/tag/%40mastra%2Fcore%401.83.0)
-   [Tài liệu tham chiếu API BroadNet Inference (kiểm tra ngày 2026-11-15) (tiếng Anh)](https://inference.broadnet.ai/docs?utm_source=broadrouter&utm_medium=referral&utm_campaign=vi-guides-mastra-openai-compatible&utm_content=sources)
