BroadRouter
시작하기

openai-go SDK로 Go에서 BroadNet Inference 호출하기

업데이트

github.com/openai/openai-go/v3를 설치하고 option.WithBaseURL("https://inference.broadnet.ai/v1")과 BroadNet 키를 넣은 option.WithAPIKey로 클라이언트를 만드세요. client.Chat.Completions.New에는 broadnet/glm-5.3 같은 BroadNet 모델 ID를 일반 문자열로 넘깁니다. Responses API가 아닌 chat completions를 쓰고, MaxTokens는 추론분까지 넉넉히 설정하세요.

openai-go는 OpenAI의 공식 Go 라이브러리입니다. option.WithBaseURL로 커스텀 base URL을 받으므로 OpenAI 호환 API라면 어디든 호출할 수 있습니다. BroadNet Inference는 https://inference.broadnet.ai/v1 주소에서 chat completions를 제공합니다. BroadRouter는 BroadNet이 운영하는 사이트이며, 이 글은 v3.99.0 기준 openai-go README를 따릅니다.

설치

go get -u 'github.com/openai/openai-go/v3@v3.99.0'
export BROADNET_API_KEY='your-broadnet-key'

현재 릴리스는 Go 1.26 이상이 필요합니다.

Chat completion 호출

package main

import (
	"context"
	"fmt"
	"os"

	"github.com/openai/openai-go/v3"
	"github.com/openai/openai-go/v3/option"
)

func main() {
	client := openai.NewClient(
		option.WithBaseURL("https://inference.broadnet.ai/v1"),
		option.WithAPIKey(os.Getenv("BROADNET_API_KEY")),
	)

	resp, err := client.Chat.Completions.New(context.TODO(), openai.ChatCompletionNewParams{
		Model: "broadnet/glm-5.3",
		Messages: []openai.ChatCompletionMessageParamUnion{
			openai.SystemMessage("You are a concise Go reviewer."),
			openai.UserMessage("How do I check if a slice is empty in Go?"),
		},
		MaxTokens: openai.Int(2000), // reasoning counts toward this limit
	})
	if err != nil {
		panic(err)
	}
	fmt.Println(resp.Choices[0].Message.Content)
}

go run .으로 실행하세요. 답이 출력되면 테스트 통과입니다. 키, URL, 모델 ID가 모두 맞다는 뜻입니다.

  • Model은 일반 문자열입니다. openai.ChatModel은 string의 타입 별칭이므로 BroadNet ID를 변환할 필요가 없습니다.
  • Chat.Completions를 쓰세요. README는 Responses API(client.Responses.New)를 먼저 소개하지만, BroadNet은 이 API를 제공한다고 표기하지 않습니다. README의 Chat Completions 절은 이 API가 “supported indefinitely”(번역: 기한 없이 지원됨)라고 밝힙니다.
  • MaxTokens와 MaxCompletionTokens. SDK는 max_tokens를 max_completion_tokens로 대체되는 deprecated 필드로 표시하지만, BroadNet API 레퍼런스가 설명하는 필드는 max_tokens입니다. MaxTokens를 쓰세요.
  • DeveloperMessage가 아니라 SystemMessage. README 예제는 developer 역할을 보내는 DeveloperMessage를 씁니다. BroadNet API 레퍼런스에는 이 역할이 나오지 않으므로 system과 user를 쓰세요.

사용량을 포함한 스트리밍

stream := client.Chat.Completions.NewStreaming(context.TODO(), openai.ChatCompletionNewParams{
	Model:     "broadnet/deepseek-v4.1-flash",
	Messages:  []openai.ChatCompletionMessageParamUnion{openai.UserMessage("Count from one to five.")},
	MaxTokens: openai.Int(2000),
	StreamOptions: openai.ChatCompletionStreamOptionsParam{
		IncludeUsage: openai.Bool(true),
	},
})
defer stream.Close()

for stream.Next() {
	chunk := stream.Current()
	if len(chunk.Choices) > 0 {
		fmt.Print(chunk.Choices[0].Delta.Content)
	}
	if chunk.Usage.TotalTokens > 0 {
		fmt.Printf("\n%d tokens\n", chunk.Usage.TotalTokens)
	}
}
if err := stream.Err(); err != nil {
	panic(err)
}

BroadNet 문서에 따르면 stream_options.include_usage가 true이면 사용량은 마지막 청크로 전달됩니다. 그 청크에는 choices가 없으므로 길이를 확인하는 것입니다. 전송 형식은 chat completions 스트리밍 가이드를 참고하세요.

오류와 재시도

SDK는 성공이 아닌 상태 코드에 대해 *openai.Error를 반환합니다. errors.As로 꺼내 StatusCode를 확인하세요.

var apierr *openai.Error
if errors.As(err, &apierr) && apierr.StatusCode == 429 {
	// back off, then retry
}

openai-go는 기본적으로 일부 오류를 짧은 지수 백오프로 두 번 재시도합니다. option.WithMaxRetries(n)으로 바꿀 수 있습니다. 재시도도 BroadNet의 요청 한도에 포함됩니다.

문제 해결

  • 401. 키가 틀렸거나, 만료되었거나, 사용 가능 금액이 소진되었습니다. WithAPIKey를 넘기지 않았다면 SDK는 OPENAI_API_KEY를 썼습니다.
  • 404. base URL은 /v1로 끝나야 하고, 호출은 Responses가 아니라 Chat.Completions로 가야 합니다. 그다음 모델 ID를 확인하세요. 유료 모델은 충전이 필요하며, 초기 크레딧($5 상당)은 broadnet/gemma-4-26b-a4b 모델과 Transcribe 모델 두 개에만 쓸 수 있습니다.
  • 비어 있는 Content. 추론이 출력 예산을 다 썼습니다. MaxTokens를 늘리세요. 답변이 비어서 오는 이유를 참고하세요.
  • 429. 종량제 키는 분당 30 요청, 동시 처리 4 건까지 허용합니다. API를 동시에 호출하는 고루틴 수를 제한하세요. 오류와 재시도를 참고하세요.

자주 묻는 질문

옵션 대신 환경 변수로 BroadNet URL을 지정할 수 있나요?

네. openai-go는 기본적으로 OPENAI_API_KEY와 OPENAI_BASE_URL을 읽으므로, 두 변수에 BroadNet 값을 넣으면 옵션 없이 openai.NewClient()만 호출해도 됩니다. option.WithBaseURL을 명시하면 OPENAI_BASE_URL보다 우선합니다.

Model 필드가 openai.ChatModel 타입인데 BroadNet 모델 ID를 어떻게 넘기나요?

openai-go에서 ChatModel은 string의 타입 별칭이므로 Model: "broadnet/glm-5.3"이 그대로 컴파일됩니다.

DeveloperMessage 대신 SystemMessage를 쓰는 이유는 무엇인가요?

DeveloperMessage는 developer 역할을 보내는데, 이는 OpenAI가 자사 모델용으로 도입한 역할입니다. BroadNet API 레퍼런스에는 이 역할이 나오지 않으므로 표준 system 역할이 더 안전합니다.

어떤 Go 버전이 필요한가요?

현재 openai-go v3는 Go 1.26 이상이 필요합니다. Go 1.25에 머물러야 한다면 README는 v3.74.0으로 고정하라고 안내합니다.

Markdown으로 읽기ChatGPT에 질문하기Claude에 질문하기Perplexity에 질문하기