BroadRouter

Dùng Spring AI với BroadNet Inference (OpenAI base-url)

Cập nhật

Thêm spring-ai-starter-model-openai, rồi đặt spring.ai.openai.base-url là https://inference.broadnet.ai/v1, spring.ai.openai.api-key là key BroadNet và spring.ai.openai.chat.model là một ID BroadNet như broadnet/glm-5.3. Đặt spring.ai.openai.chat.max-tokens có chừa chỗ cho suy luận. Spring AI 2.x dùng SDK openai-java, vốn tự nối /chat/completions vào base URL.

Spring AI là framework của dự án Spring để dùng AI trong Java. OpenAI chat starter của nó đọc thuộc tính base-url, nên có thể gọi bất kỳ server tương thích OpenAI nào. BroadNet Inference phục vụ chat completions chuẩn tại https://inference.broadnet.ai/v1. BroadRouter là website của chính BroadNet; bài này làm theo tài liệu tham chiếu Spring AI 2.0.2.

Thêm starter

Khi đã có Spring AI BOM (xem tài liệu quản lý dependency của Spring AI):

<dependency>
  <groupId>org.springframework.ai</groupId>
  <artifactId>spring-ai-starter-model-openai</artifactId>
</dependency>

Cấu hình

application.properties:

spring.ai.openai.base-url=https://inference.broadnet.ai/v1
spring.ai.openai.api-key=${BROADNET_API_KEY}
spring.ai.openai.chat.model=broadnet/glm-5.3
spring.ai.openai.chat.max-tokens=2000
export BROADNET_API_KEY='your-broadnet-key'

Hãy giữ /v1 trong URL. Trong Spring AI 2.x, giá trị này được chuyển nguyên văn cho client openai-java (OpenAiSetup.calculateBaseUrl trả về đúng như cũ), và client đó tự thêm /chat/completions. Giá trị mặc định bị thay thế là https://api.openai.com/v1.

Gọi và chạy thử

import org.springframework.ai.chat.client.ChatClient;
import org.springframework.boot.CommandLineRunner;
import org.springframework.context.annotation.Bean;

@Bean
CommandLineRunner smokeTest(ChatClient.Builder builder) {
    return args -> {
        ChatClient chat = builder.build();
        System.out.println(chat.prompt().user("Say hello in five words.").call().content());
    };
}

Khởi động ứng dụng. Nếu có câu trả lời được in ra, key, URL và model ID đều đúng.

Những cài đặt quan trọng với BroadNet

  • max-tokens, không phải max-completion-tokens. Tài liệu Spring AI nói hai thuộc tính này loại trừ nhau và đặt cả hai sẽ gây lỗi. Tài liệu tham chiếu API của BroadNet mô tả max_tokens. DeepSeek V4.1 Flash, GLM 5.3 và Qwen3.8 27B suy luận trước, và phần suy luận được tính vào giới hạn.
  • Văn bản suy luận. Spring AI có thể hiển thị reasoning_content từ các server tương thích OpenAI có trả về trường này. Tài liệu tham chiếu API của BroadNet báo số token suy luận trong usage nhưng không cam kết trả về chính văn bản suy luận, nên đừng phụ thuộc vào nó.
  • Ghi đè chỉ cho chat. spring.ai.openai.chat.base-url và spring.ai.openai.chat.api-key được ưu tiên hơn các thuộc tính dùng chung, chỉ cho model chat. Hãy dùng chúng nếu các model OpenAI khác trong Spring AI (như embeddings) phải ở lại OpenAI.
  • Thử lại. spring.ai.retry.max-attempts mặc định là 10 với exponential backoff. Trên key trả theo mức dùng, điều đó có thể nhanh chóng dùng hết giới hạn mỗi phút; hãy cân nhắc giảm giá trị này.

Chọn model nào

Mục đích spring.ai.openai.chat.model
Gọi tool, đầu ra có cấu trúc broadnet/glm-5.3
Hình ảnh hoặc văn bản tiếng Ả Rập broadnet/qwen3.8-27b
Tài liệu dài, gói giá cố định broadnet/deepseek-v4.1-flash
Tín dụng ban đầu miễn phí broadnet/gemma-4-26b-a4b

Giá của mọi model.

Xử lý sự cố

  • 401. Key sai, đã hết hạn hoặc đã hết hạn mức, hoặc BROADNET_API_KEY chưa được đặt cho JVM.
  • 404. Base URL thiếu /v1, hoặc model ID sai. Các model trả phí cần nạp tiền; tín dụng $5 chỉ dùng được cho broadnet/gemma-4-26b-a4b và hai model Transcribe.
  • content() rỗng. Suy luận đã dùng hết ngân sách đầu ra. Hãy tăng max-tokens. Vì sao câu trả lời trả về rỗng.
  • Lỗi 400 khi đặt cả hai giới hạn token. Hãy bỏ max-completion-tokens.
  • 429. 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. Xem lỗi và thử lại.

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

spring.ai.openai.base-url có cần chứa /v1 không?

Có. Trong Spring AI 2.x, giá trị này được chuyển nguyên văn cho client openai-java, mà giá trị mặc định của chính client đó là https://api.openai.com/v1. Hãy dùng https://inference.broadnet.ai/v1.

Với BroadNet nên dùng max-tokens hay max-completion-tokens?

Dùng max-tokens. Tài liệu Spring AI nói hai thuộc tính này loại trừ nhau. Tài liệu tham chiếu API của BroadNet mô tả trường max_tokens, và suy luận được tính vào đó, nên hãy cho phép từ 1.000 token trở lên.

Gọi tool của Spring AI có chạy với BroadNet không?

Hãy dùng GLM 5.3 hoặc Qwen3.8 27B, là các model BroadNet liệt kê có tool. Tài liệu BroadNet không liệt kê gọi tool cho DeepSeek V4.1 Flash.

Có thể giữ OpenAI cho embeddings và dùng BroadNet cho chat không?

Có. spring.ai.openai.chat.base-url và spring.ai.openai.chat.api-key ghi đè các thuộc tính dùng chung, chỉ cho model chat. Tài liệu tham chiếu API của BroadNet không liệt kê endpoint embeddings.

Đọc dạng MarkdownHỏi ChatGPTHỏi ClaudeHỏi Perplexity