---
title: "Haystack OpenAIChatGenerator com api_base_url personalizado"
description: "Aponte o OpenAIChatGenerator do Haystack para a BroadNet Inference com api_base_url, um ID de modelo da BroadNet e uma chave Secret, para pipelines, tools e agentes."
url: https://broadrouter.com/pt/guides/haystack-openai-compatible/
lang: pt-BR
updated: 2026-11-16
publisher: BroadRouter (a BroadNet site); API by BroadNet Inference, https://inference.broadnet.ai
---

Traduzido do inglês com ajuda de IA. [Leia o original em inglês](https://broadrouter.com/guides/haystack-openai-compatible/) (atualizado em 2026-11-16).

# Usar pipelines e agentes do Haystack com a BroadNet Inference

Atualizado em 2026-11-16

Instale o haystack-ai e crie um OpenAIChatGenerator com api\_base\_url em https://inference.broadnet.ai/v1, api\_key como um Secret lido de BROADNET\_API\_KEY e model com um ID da BroadNet como broadnet/glm-5.3. Use-o em pipelines ou em um Agent do Haystack. Passe max\_tokens em generation\_kwargs e, quando o generator tiver ferramentas, use GLM 5.3 ou Qwen3.8 27B.

O Haystack é o framework open source da deepset para pipelines de RAG e agentes. O `OpenAIChatGenerator` dele conversa com qualquer servidor compatível com a OpenAI por meio de `api_base_url`. A BroadNet Inference oferece chat completions padrão em `https://inference.broadnet.ai/v1`, então esse é o componente a usar. O BroadRouter é o site da própria BroadNet; este guia segue a documentação do Haystack 3.5.

## Instalação

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

## Conexão

```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`** é enviado sem alteração. Use o ID da BroadNet com o prefixo `broadnet/`.
-   **`api_key`** é um `Secret` do Haystack. Sem ele, o Haystack procura `OPENAI_API_KEY`.
-   **`generation_kwargs`** vão para a requisição de chat completion. Defina `max_tokens` alto o bastante para o raciocínio (veja abaixo).

## Resposta em streaming

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

Aí o Haystack envia `stream: true` com `stream_options.include_usage`, e a contagem de tokens chega no último chunk. A documentação da BroadNet descreve a mesma opção.

## Ferramentas e agentes

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

A documentação da BroadNet lista ferramentas e saída estruturada só para `broadnet/glm-5.3` e `broadnet/qwen3.8-27b`. Deixe `tools_strict` no padrão, `False`, a menos que você tenha testado schemas strict.

## Qual modelo escolher

| Pipeline | Modelo |
| --- | --- |
| Agentes e chamadas de ferramenta | `broadnet/glm-5.3` |
| RAG sobre páginas digitalizadas ou texto em árabe, com ferramentas | `broadnet/qwen3.8-27b` |
| Respostas com contexto longo em um plano de preço fixo | `broadnet/deepseek-v4.1-flash` |
| Testar com o crédito inicial gratuito | `broadnet/gemma-4-26b-a4b` (contexto de 32.768 tokens) |

O contexto recuperado pode ser grande. GLM 5.3 e DeepSeek V4.1 Flash aceitam 1.048.576 tokens de contexto; os 32.768 do Gemma enchem rápido. [Preços de todos os modelos](https://broadrouter.com/pt/pricing/).

## Como testamos

Em 2026-11-15 instalamos o haystack-ai 3.5.0 em um ambiente virtual limpo e rodamos os exemplos acima (simples, streaming, ferramentas e Agent) contra um servidor mock local que imita o formato de chat completions da BroadNet. Lemos as requisições registradas. Todas foram para `/v1/chat/completions` com o ID do modelo sem alteração, uma chave Bearer, `max_tokens` vindo de `generation_kwargs` e, no caso das ferramentas, o schema da função. O Haystack também envia `n: 1`. Não tínhamos uma chave da BroadNet, então não testamos a saída real dos modelos.

## Solução de problemas

-   **401.** A chave está errada, expirou ou ficou sem cota, ou `BROADNET_API_KEY` não está definida no processo que roda o pipeline.
-   **404.** `api_base_url` precisa terminar em `/v1`, e o ID do modelo precisa ser exatamente o da BroadNet. Os modelos pagos exigem uma recarga; o crédito de $5 cobre só `broadnet/gemma-4-26b-a4b` e os dois modelos Transcribe.
-   **Respostas vazias.** DeepSeek V4.1 Flash, GLM 5.3 e Qwen3.8 27B raciocinam antes de responder, e o raciocínio conta para `max_tokens`. Aumente o valor. [Por que as respostas vêm vazias](https://broadrouter.com/pt/guides/reasoning-tokens-empty-response/).
-   **429 em indexação ou avaliação em lote.** Uma chave de pagamento por uso permite 30 requisições por minuto e 4 em andamento. Use o `max_retries` do generator e veja [erros e novas tentativas](https://broadrouter.com/pt/guides/errors-and-retries/).

## Termos neste guia

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

Um token é a unidade de texto que um modelo de linguagem lê e escreve: uma palavra, parte de uma palavra, um sinal de pontuação ou uma sequência de bytes gerada pelo tokenizador do modelo. As APIs de LLM contam, limitam e normalmente cobram o uso em tokens.

[Tool calling (chamada de ferramentas)](https://broadrouter.com/pt/glossary/tool-calling/)

Tool calling, também chamado de function calling ou chamada de ferramentas, é um recurso de APIs de LLM em que o modelo devolve um pedido estruturado para executar uma função definida pelo desenvolvedor, com argumentos JSON. A aplicação executa a função e devolve o resultado; o modelo nunca executa código sozinho.

[Streaming](https://broadrouter.com/pt/glossary/streaming/)

Streaming é uma forma de devolver a resposta de um modelo de linguagem em pequenos pedaços enquanto ela ainda está sendo gerada, em vez de uma resposta única no final. APIs compatíveis com a OpenAI fazem streaming via server-sent events quando a requisição define stream como true.

[Pagamento por uso (pay-as-you-go)](https://broadrouter.com/pt/glossary/pay-as-you-go/)

Pagamento por uso é um modelo de preço em que você paga só pelo que usa, medido por unidade, como tokens, requisições ou minutos de áudio, sem assinatura nem compromisso mínimo. A maioria das APIs de LLM cobra assim, a partir de um saldo pré-pago ou de uma fatura periódica.

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

A Chat Completions API é o endpoint HTTP da OpenAI, POST /v1/chat/completions, que recebe o nome de um modelo e uma lista de mensagens marcadas com papéis e devolve a próxima mensagem do modelo. O formato da requisição e da resposta virou o padrão comum que provedores e SDKs compatíveis com a OpenAI reutilizam.

[Concorrência (concurrency)](https://broadrouter.com/pt/glossary/concurrency/)

Concorrência é o número de requisições que um cliente tem em andamento ao mesmo tempo. APIs de LLM muitas vezes a limitam por chave ou por plano, separadamente das requisições por minuto, porque cada requisição aberta ocupa capacidade de GPU até a resposta terminar.

[Rate limit (limite de taxa)](https://broadrouter.com/pt/glossary/rate-limit/)

Um rate limit é um teto que uma API impõe a quanto um cliente pode usá-la em um intervalo de tempo, como requisições por minuto ou tokens por minuto. As requisições acima do limite são recusadas, normalmente com HTTP 429 Too Many Requests, até que o uso volte a ficar abaixo dele.

[Crédito pré-pago (prepaid credit)](https://broadrouter.com/pt/glossary/prepaid-credit/)

Crédito pré-pago é dinheiro adicionado a uma conta de API antes do uso. Cada requisição desconta o próprio custo do saldo e, quando o saldo acaba, as requisições cobradas por uso param até você fazer uma recarga. Ele limita o gasto ao que você já pagou.

## Perguntas frequentes

### Qual parâmetro do Haystack define a URL da BroadNet?

O api\_base\_url do OpenAIChatGenerator. A documentação do Haystack o apresenta como a forma de acessar deployments personalizados. Defina como https://inference.broadnet.ai/v1.

### Devo usar o OpenAIResponsesChatGenerator com a BroadNet?

Não. Esse componente chama a Responses API da OpenAI, que a BroadNet não lista. Use o OpenAIChatGenerator, que chama chat completions.

### Por que o Haystack falha dizendo que falta OPENAI\_API\_KEY?

O padrão de api\_key é Secret.from\_env\_var("OPENAI\_API\_KEY"). Passe api\_key=Secret.from\_env\_var("BROADNET\_API\_KEY") para o Haystack ler a sua chave da BroadNet.

### Um Agent do Haystack consegue chamar ferramentas na BroadNet?

Sim, com um modelo que a BroadNet lista com ferramentas: GLM 5.3 ou Qwen3.8 27B. No nosso teste com servidor mock, o Agent enviou o schema da ferramenta via chat completions e recebeu a chamada de ferramenta de volta.

## Guias relacionados

-   [Como usar o SDK Python da OpenAI com a BroadNet Inference](https://broadrouter.com/pt/guides/openai-python-sdk/)
-   [Usar o LlamaIndex com a BroadNet Inference via OpenAILike](https://broadrouter.com/pt/guides/llamaindex-openailike/)
-   [Por que um modelo de raciocínio devolve uma resposta vazia](https://broadrouter.com/pt/guides/reasoning-tokens-empty-response/)
-   [Códigos de erro da BroadNet Inference e quando tentar de novo](https://broadrouter.com/pt/guides/errors-and-retries/)
-   [Todas as ferramentas que funcionam com a BroadNet Inference (em inglês)](https://broadrouter.com/integrations/): SDKs, agentes de programação, interfaces de chat e ferramentas de automação, com as configurações exatas de cada uma

Teste com a sua carga de trabalho real. Contas novas começam com US$ 5 de crédito para Gemma e transcrição. DeepSeek, GLM e Qwen3.8 exigem uma recarga.

[Começar](https://inference.broadnet.ai/account/?utm_source=broadrouter&utm_medium=referral&utm_campaign=pt-guides-haystack-openai-compatible&utm_content=page-cta) ·

**Fontes**

-   [Documentação do Haystack 3.5, OpenAIChatGenerator (conferido em 2026-11-15)](https://docs.haystack.deepset.ai/docs/openaichatgenerator)
-   [PyPI, haystack-ai 3.5.0, Python 3.11+ (conferido em 2026-11-15)](https://pypi.org/project/haystack-ai/)
-   [Referência da API da BroadNet Inference (conferido em 2026-11-15) (em inglês)](https://inference.broadnet.ai/docs?utm_source=broadrouter&utm_medium=referral&utm_campaign=pt-guides-haystack-openai-compatible&utm_content=sources)
