---
title: "Haystack OpenAIChatGenerator 커스텀 api_base_url 설정 | BroadRouter"
description: "api_base_url, BroadNet 모델 ID, Secret 키로 Haystack의 OpenAIChatGenerator를 BroadNet Inference에 연결해 파이프라인, 도구, 스트리밍, 에이전트에 씁니다."
url: https://broadrouter.com/ko/guides/haystack-openai-compatible/
lang: ko
updated: 2026-11-16
publisher: BroadRouter (a BroadNet site); API by BroadNet Inference, https://inference.broadnet.ai
---

이 페이지는 영어 원문을 AI의 도움을 받아 번역했습니다. [영어 원문 읽기](https://broadrouter.com/guides/haystack-openai-compatible/) (2026-11-16 업데이트).

# Haystack 파이프라인과 에이전트를 BroadNet Inference로 실행하기

업데이트 2026-11-16

haystack-ai를 설치하고 OpenAIChatGenerator를 만들 때 api\_base\_url은 https://inference.broadnet.ai/v1, api\_key는 BROADNET\_API\_KEY에서 읽는 Secret, model은 broadnet/glm-5.3 같은 BroadNet ID로 지정하세요. 이 생성기를 파이프라인이나 Haystack Agent에서 쓰면 됩니다. max\_tokens는 generation\_kwargs로 넘기고, 생성기에 도구를 붙일 때는 GLM 5.3이나 Qwen3.8 27B를 쓰세요.

Haystack은 deepset이 만든 RAG 파이프라인 및 에이전트용 오픈 소스 프레임워크입니다. Haystack의 `OpenAIChatGenerator`는 `api_base_url`을 통해 어떤 OpenAI 호환 서버와도 통신합니다. BroadNet Inference는 `https://inference.broadnet.ai/v1` 주소에서 표준 chat completions를 제공하므로 이 컴포넌트를 쓰면 됩니다. BroadRouter는 BroadNet이 운영하는 사이트이며, 이 글은 Haystack 3.5 문서를 따릅니다.

## 설치

```bash
pip install haystack-ai
export BROADNET_API_KEY='your-broadnet-key'
```

## 연결

```python
from haystack.components.generators.chat import OpenAIChatGenerator
from haystack.dataclasses import ChatMessage
from haystack.utils import Secret

generator = OpenAIChatGenerator(
    api_base_url="https://inference.broadnet.ai/v1",
    api_key=Secret.from_env_var("BROADNET_API_KEY"),
    model="broadnet/glm-5.3",
    generation_kwargs={"max_tokens": 4000},
)

reply = generator.run([ChatMessage.from_user("Name three uses of a RAG pipeline.")])
print(reply["replies"][0].text)
```

-   **`model`** 값은 그대로 전송됩니다. `broadnet/` 접두사가 붙은 BroadNet ID를 쓰세요.
-   \*\*`api_key`\*\*는 Haystack의 `Secret`입니다. 지정하지 않으면 Haystack은 `OPENAI_API_KEY`를 찾습니다.
-   \*\*`generation_kwargs`\*\*는 chat completion 요청에 그대로 전달됩니다. `max_tokens`는 추론에 충분할 만큼 높게 잡으세요(아래 참고).

## 답변 스트리밍

```python
from haystack.components.generators.utils import print_streaming_chunk

generator = OpenAIChatGenerator(
    api_base_url="https://inference.broadnet.ai/v1",
    api_key=Secret.from_env_var("BROADNET_API_KEY"),
    model="broadnet/glm-5.3",
    streaming_callback=print_streaming_chunk,
)
```

이렇게 하면 Haystack은 `stream: true`와 `stream_options.include_usage`를 함께 보내므로, 토큰 사용량이 마지막 청크에 담겨 옵니다. BroadNet 문서도 같은 옵션을 설명합니다.

## 도구와 에이전트

```python
from haystack.components.agents import Agent
from haystack.tools import Tool

def get_weather(city: str) -> str:
    return f"21C in {city}"

weather = Tool(
    name="get_weather",
    description="Get the weather for a city",
    parameters={"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]},
    function=get_weather,
)

chat = OpenAIChatGenerator(
    api_base_url="https://inference.broadnet.ai/v1",
    api_key=Secret.from_env_var("BROADNET_API_KEY"),
    model="broadnet/glm-5.3",
    tools=[weather],
)
agent = Agent(chat_generator=chat, tools=[weather])
result = agent.run(messages=[ChatMessage.from_user("What's the weather in Riyadh?")])
print(result["messages"][-1].text)
```

BroadNet 문서는 도구와 구조화된 출력을 `broadnet/glm-5.3`, `broadnet/qwen3.8-27b` 두 모델에만 표기합니다. 엄격한 스키마를 직접 테스트하기 전까지는 `tools_strict`를 기본값 `False`로 두세요.

## 어떤 모델을 고를까

| 파이프라인 | 모델 |
| --- | --- |
| 에이전트와 도구 호출 | `broadnet/glm-5.3` |
| 스캔한 페이지나 아랍어 텍스트 대상 RAG, 도구 사용 | `broadnet/qwen3.8-27b` |
| 정액 플랜에서 긴 컨텍스트 답변 | `broadnet/deepseek-v4.1-flash` |
| 무료 초기 크레딧으로 체험 | `broadnet/gemma-4-26b-a4b` (32,768 토큰 컨텍스트) |

검색해 온 컨텍스트는 클 수 있습니다. GLM 5.3과 DeepSeek V4.1 Flash는 1,048,576 토큰의 컨텍스트를 받지만, Gemma의 32,768 토큰은 금방 찹니다. [모든 모델의 가격](https://broadrouter.com/ko/pricing/)을 확인하세요.

## 테스트 방법

2026-11-15에 깨끗한 가상 환경에 haystack-ai 3.5.0을 설치하고, 위의 기본, 스트리밍, 도구, Agent 예제를 BroadNet의 chat completions 형식을 흉내 내는 로컬 모의 서버에 대고 실행했습니다. 기록된 요청을 확인해 보니 모두 `/v1/chat/completions`로 갔고, 모델 ID는 바뀌지 않았으며, Bearer 키, `generation_kwargs`에서 온 `max_tokens`, 그리고 도구 예제에서는 함수 스키마가 포함되었습니다. Haystack은 `n: 1`도 함께 보냅니다. BroadNet 키가 없었기 때문에 실제 모델 출력은 테스트하지 않았습니다.

## 문제 해결

-   **401.** 키가 틀렸거나 만료되었거나 사용 가능 금액이 소진되었습니다. 또는 파이프라인을 실행하는 프로세스에 `BROADNET_API_KEY`가 설정되지 않았습니다.
-   **404.** `api_base_url`은 `/v1`로 끝나야 하고, 모델 ID는 BroadNet ID와 정확히 일치해야 합니다. 유료 모델은 충전이 필요하며, 초기 크레딧($5 상당)으로는 `broadnet/gemma-4-26b-a4b` 모델과 Transcribe 모델 두 개만 쓸 수 있습니다.
-   **빈 응답.** DeepSeek V4.1 Flash, GLM 5.3, Qwen3.8 27B는 답하기 전에 추론하며, 그 추론도 `max_tokens`에 포함됩니다. 값을 늘리세요. [답변이 비어서 오는 이유](https://broadrouter.com/ko/guides/reasoning-tokens-empty-response/)를 참고하세요.
-   **일괄 색인이나 평가 중 429.** 종량제 키는 분당 30 요청, 동시 처리 4 건까지 허용합니다. 생성기의 `max_retries`를 쓰고 [오류와 재시도](https://broadrouter.com/ko/guides/errors-and-retries/)를 참고하세요.

## 이 가이드의 용어

[종량제(Pay-as-you-go)](https://broadrouter.com/ko/glossary/pay-as-you-go/)

종량제(pay-as-you-go)는 구독이나 최소 약정 없이 토큰, 요청, 오디오 분 같은 단위로 사용량을 측정해 쓴 만큼만 내는 요금 방식입니다. 대부분의 LLM API가 선불 잔액에서 차감하거나 정기 청구서를 발행하는 식으로 이렇게 과금합니다.

[도구 호출(tool calling)](https://broadrouter.com/ko/glossary/tool-calling/)

도구 호출(tool calling)은 함수 호출(function calling)이라고도 하며, 모델이 개발자가 정의한 함수를 실행해 달라는 구조화된 요청을 JSON 인자와 함께 반환하는 LLM API 기능입니다. 함수는 애플리케이션이 실행하고 그 결과를 다시 보냅니다. 모델이 직접 코드를 실행하지는 않습니다.

[동시 처리(concurrency)](https://broadrouter.com/ko/glossary/concurrency/)

동시 처리(concurrency)는 클라이언트가 같은 시점에 진행 중인 요청 수입니다. LLM API는 분당 요청 수와 별도로 키나 플랜마다 이를 제한하는 경우가 많습니다. 열려 있는 요청은 응답이 끝날 때까지 GPU 용량을 차지하기 때문입니다.

[속도 제한(rate limit)](https://broadrouter.com/ko/glossary/rate-limit/)

속도 제한(rate limit)은 API가 일정 시간 동안 클라이언트가 사용할 수 있는 양에 두는 상한으로, 분당 요청 수나 분당 토큰 수 같은 기준이 있습니다. 한도를 넘은 요청은 사용량이 다시 한도 아래로 내려갈 때까지 거부되며, 보통 HTTP 429 Too Many Requests가 반환됩니다.

[AI 에이전트(AI agent)](https://broadrouter.com/ko/glossary/agent/)

AI 에이전트는 언어 모델이 목표를 향해 스스로 단계를 정하는 시스템입니다. 어떤 도구를 호출할지 결정하고, 결과를 읽고, 최종 답변을 내거나 한도에 닿을 때까지 이를 반복합니다. 정해진 지점에서 모델을 호출하는 고정된 스크립트는 보통 워크플로라고 부릅니다.

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

Chat Completions API는 OpenAI의 HTTP 엔드포인트인 POST /v1/chat/completions로, 모델 이름과 역할이 붙은 메시지 목록을 받아 모델의 다음 메시지를 반환합니다. 이 요청과 응답 구조는 OpenAI 호환 제공업체와 SDK가 재사용하는 공통 형식이 되었습니다.

[OpenAI 호환 API(OpenAI-compatible API)](https://broadrouter.com/ko/glossary/openai-compatible-api/)

OpenAI 호환 API는 POST /v1/chat/completions처럼 OpenAI API와 같은 요청 및 응답 형식을 받는 HTTP API입니다. 그래서 OpenAI SDK와 도구는 base URL, API 키, 모델 이름만 바꾸면 이 API를 그대로 사용할 수 있습니다.

[RAG(검색 증강 생성)](https://broadrouter.com/ko/glossary/rag/)

RAG(검색 증강 생성, retrieval-augmented generation)는 애플리케이션이 먼저 검색 인덱스나 벡터 인덱스 같은 외부 저장소에서 질문과 관련된 구절을 찾고, 이를 프롬프트에 추가해 언어 모델이 기억에만 의존하지 않고 그 텍스트를 바탕으로 답하게 하는 패턴입니다.

## 자주 묻는 질문

### Haystack에서 BroadNet URL은 어떤 파라미터로 지정하나요?

OpenAIChatGenerator의 api\_base\_url입니다. Haystack 문서는 이 파라미터를 커스텀 배포에 연결하는 방법으로 설명합니다. https://inference.broadnet.ai/v1로 설정하세요.

### BroadNet에서 OpenAIResponsesChatGenerator를 써도 되나요?

아니요. 이 컴포넌트는 OpenAI의 Responses API를 호출하는데, BroadNet은 이 API를 표기하지 않습니다. chat completions를 호출하는 OpenAIChatGenerator를 쓰세요.

### Haystack이 OPENAI\_API\_KEY가 없다며 실패하는 이유는 무엇인가요?

api\_key의 기본값이 Secret.from\_env\_var("OPENAI\_API\_KEY")이기 때문입니다. api\_key=Secret.from\_env\_var("BROADNET\_API\_KEY")를 넘기면 Haystack이 BroadNet 키를 읽습니다.

### Haystack Agent가 BroadNet에서 도구를 호출할 수 있나요?

네. BroadNet이 도구를 표기한 모델인 GLM 5.3이나 Qwen3.8 27B를 쓰면 됩니다. 모의 서버 테스트에서 Agent는 chat completions로 도구 스키마를 보냈고 도구 호출을 돌려받았습니다.

## 관련 가이드

-   [BroadNet Inference에서 OpenAI Python SDK 사용하기](https://broadrouter.com/ko/guides/openai-python-sdk/)
-   [OpenAILike로 LlamaIndex와 BroadNet Inference 연결하기](https://broadrouter.com/ko/guides/llamaindex-openailike/)
-   [추론 모델이 빈 답변을 반환하는 이유](https://broadrouter.com/ko/guides/reasoning-tokens-empty-response/)
-   [BroadNet Inference 오류 코드와 재시도해야 하는 경우](https://broadrouter.com/ko/guides/errors-and-retries/)
-   [BroadNet Inference와 함께 쓸 수 있는 모든 도구 (영어)](https://broadrouter.com/integrations/): SDK, 코딩 에이전트, 채팅 UI, 자동화 도구와 각 도구의 정확한 설정

실제 워크로드로 테스트해 보세요. 신규 계정에는 US$5 상당의 초기 크레딧이 제공되며 Gemma 및 음성 전사에 사용할 수 있습니다. DeepSeek, GLM 및 Qwen3.8 모델은 충전이 필요합니다.

[시작하기](https://inference.broadnet.ai/account/?utm_source=broadrouter&utm_medium=referral&utm_campaign=ko-guides-haystack-openai-compatible&utm_content=page-cta) ·

**출처**

-   [Haystack 문서 3.5, OpenAIChatGenerator(2026-11-15 확인)](https://docs.haystack.deepset.ai/docs/openaichatgenerator)
-   [PyPI, haystack-ai 3.5.0, Python 3.11 이상(2026-11-15 확인)](https://pypi.org/project/haystack-ai/)
-   [BroadNet Inference API 레퍼런스(2026-11-15 확인) (영어)](https://inference.broadnet.ai/docs?utm_source=broadrouter&utm_medium=referral&utm_campaign=ko-guides-haystack-openai-compatible&utm_content=sources)
