> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Integração com o framework LlamaIndex

> Conecte o LlamaIndex ao AI Gateway do Toqan Router para ter observabilidade completa, confiabilidade integrada e acesso a mais de 500 LLMs de mais de 30 provedores.

> [card] [AI Gateway](#ai-gateway)
>
> Roteie suas chamadas de LLM pelo AI Gateway alterando apenas a base URL. Sem dependência de fornecedor: use sempre o melhor modelo pelo menor custo para o seu caso de uso.

> [card] [Observabilidade](#observability)
>
> Instrumente seu código com OpenTelemetry para capturar traces, logs e métricas de cada chamada de LLM, etapa de agente e uso de ferramenta.

## AI Gateway

### Visão geral

O LlamaIndex é um framework poderoso para criar aplicações de RAG (Retrieval-Augmented Generation) com LLMs. Ao conectar o LlamaIndex ao AI Gateway do Toqan Router, você transforma aplicações de RAG experimentais em sistemas prontos para produção com recursos de nível empresarial.

### Principais benefícios

O AI Gateway do Toqan Router aprimora suas aplicações LlamaIndex com:

> [card] Observabilidade completa
>
> Acompanhe a indexação de documentos, o desempenho da recuperação e o processamento de consultas com traces detalhados

> [card] Confiabilidade integrada
>
> Fallbacks automáticos, novas tentativas e balanceamento de carga para resiliência em produção

> [card] Otimização de custos
>
> Acompanhamento de custos em tempo real e gestão de gastos em todas as suas operações de IA

> [card] Acesso a múltiplos provedores
>
> Acesse mais de 500 LLMs e mais de 30 provedores por meio de uma integração única e unificada

### Pré-requisitos

Antes de integrar o LlamaIndex ao Toqan Router, certifique-se de ter:

* Uma conta no Toqan Router e uma chave de API
* Python 3.8 ou superior
* O LlamaIndex instalado no seu projeto

> [!NOTE]
>
> Para configurar sua chave de API, consulte Chaves de API e endpoints.

### Instalação

Instale o LlamaIndex e as dependências necessárias:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
pip install llama-index llama-index-llms-openai-like
```

### Configuração

Configure o LlamaIndex para usar o AI Gateway do Toqan Router com a classe `OpenAILike`:

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from llama_index.llms.openai_like import OpenAILike
import os

# Configure OpenAI-compatible LLM with Toqan Router AI Gateway
llm = OpenAILike(
    model="openai/gpt-5.6-sol",
    api_key=os.getenv("TOQAN_API_KEY"),
    api_base="https://router.toqan.ai/eu/v3/router",
    is_chat_model=True,
)
```

> **api\_base**: `https://router.toqan.ai/eu/v3/router`

### Exemplo básico de RAG

Veja um exemplo completo de criação de uma aplicação de RAG com o LlamaIndex por meio do Toqan Router:

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from llama_index.core import VectorStoreIndex, SimpleDirectoryReader, Settings
from llama_index.llms.openai_like import OpenAILike
from llama_index.embeddings.openai import OpenAIEmbedding
import os

# Configure LLM with Toqan Router AI Gateway
llm = OpenAILike(
    model="openai/gpt-5.6-sol",
    api_key=os.getenv("TOQAN_API_KEY"),
    api_base="https://router.toqan.ai/eu/v3/router",
    is_chat_model=True,
)

# Configure embeddings through Toqan Router (required - LlamaIndex defaults to OpenAI)
embed_model = OpenAIEmbedding(
    model="openai/text-embedding-3-small",
    api_key=os.getenv("TOQAN_API_KEY"),
    api_base="https://router.toqan.ai/eu/v3/router",
)

# Set as global defaults
Settings.llm = llm
Settings.embed_model = embed_model

# Load documents and create index
documents = SimpleDirectoryReader("./data").load_data()
index = VectorStoreIndex.from_documents(documents)

# Query the index
query_engine = index.as_query_engine()
response = query_engine.query("What is the main topic of these documents?")
print(response)
```

### Seleção de modelo

Com o Toqan Router, você pode usar qualquer modelo compatível de mais de 30 provedores:

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from llama_index.llms.openai_like import OpenAILike
import os

# Use Claude
claude_llm = OpenAILike(
    model="anthropic/claude-sonnet-5",
    api_key=os.getenv("TOQAN_API_KEY"),
    api_base="https://router.toqan.ai/eu/v3/router",
    is_chat_model=True,
)

# Use Gemini
gemini_llm = OpenAILike(
    model="google-ai/gemini-2.5-flash",
    api_key=os.getenv("TOQAN_API_KEY"),
    api_base="https://router.toqan.ai/eu/v3/router",
    is_chat_model=True,
)

# Use any other model
groq_llm = OpenAILike(
    model="groq/qwen/qwen3.8-27b",
    api_key=os.getenv("TOQAN_API_KEY"),
    api_base="https://router.toqan.ai/eu/v3/router",
    is_chat_model=True,
)
```

### Respostas em streaming

O LlamaIndex oferece suporte a streaming com o Toqan Router:

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from llama_index.core import VectorStoreIndex, SimpleDirectoryReader, Settings
from llama_index.llms.openai_like import OpenAILike
from llama_index.embeddings.openai import OpenAIEmbedding
import os

# Configure LLM
llm = OpenAILike(
    model="openai/gpt-5.6-sol",
    api_key=os.getenv("TOQAN_API_KEY"),
    api_base="https://router.toqan.ai/eu/v3/router",
    is_chat_model=True,
)

# Configure embeddings
embed_model = OpenAIEmbedding(
    model="openai/text-embedding-3-small",
    api_key=os.getenv("TOQAN_API_KEY"),
    api_base="https://router.toqan.ai/eu/v3/router",
)

Settings.llm = llm
Settings.embed_model = embed_model

# Create index and query engine
documents = SimpleDirectoryReader("./data").load_data()
index = VectorStoreIndex.from_documents(documents)
query_engine = index.as_query_engine(streaming=True)

# Stream response
streaming_response = query_engine.query("Explain the main concepts")
for text in streaming_response.response_gen:
    print(text, end="", flush=True)
print()
```

## Observabilidade

### Primeiros passos

Integre o LlamaIndex à observabilidade do Toqan Router para obter insights abrangentes sobre indexação de documentos, desempenho da recuperação, processamento de consultas e interações com LLMs usando OpenTelemetry.

### Pré-requisitos

Antes de começar, certifique-se de ter:

* Uma conta no Toqan Router e uma chave de API
* O LlamaIndex instalado no seu projeto
* Python 3.8+
* Chave de API da OpenAI (ou credenciais de outro provedor de LLM)

### Instalar dependências

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Core LlamaIndex and OpenInference packages
pip install llama-index openinference-instrumentation-llama-index

# OpenTelemetry packages
pip install opentelemetry-sdk opentelemetry-exporter-otlp-proto-http

# LLM providers
pip install openai anthropic

# Optional: For advanced vector stores and embeddings
pip install llama-index-vector-stores-chroma llama-index-embeddings-openai
```

### Configurar o Toqan Router

Configure suas variáveis de ambiente para se conectar ao coletor OpenTelemetry do Toqan Router:

**Unix/Linux/macOS:**

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
export OTEL_EXPORTER_OTLP_ENDPOINT="https://router.toqan.ai/eu/v2/otel"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer <TOQAN_API_KEY>"
export OTEL_RESOURCE_ATTRIBUTES="service.name=llamaindex-app,service.version=1.0.0"
export OPENAI_API_KEY="<YOUR_OPENAI_API_KEY>"
```

**Windows (PowerShell):**

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
$env:OTEL_EXPORTER_OTLP_ENDPOINT = "https://router.toqan.ai/eu/v2/otel"
$env:OTEL_EXPORTER_OTLP_HEADERS = "Authorization=Bearer <TOQAN_API_KEY>"
$env:OTEL_RESOURCE_ATTRIBUTES = "service.name=llamaindex-app,service.version=1.0.0"
$env:OPENAI_API_KEY = "<YOUR_OPENAI_API_KEY>"
```

**Usando um arquivo .env:**

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
OTEL_EXPORTER_OTLP_ENDPOINT=https://router.toqan.ai/eu/v2/otel
OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer <TOQAN_API_KEY>
OTEL_RESOURCE_ATTRIBUTES=service.name=llamaindex-app,service.version=1.0.0
OPENAI_API_KEY=<YOUR_OPENAI_API_KEY>
```

### Exemplo de integração

> [!NOTE]
>
> Usaremos o OpenInference como TracerProvider com o LlamaIndex

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from openinference.instrumentation.llama_index import LlamaIndexInstrumentor
from opentelemetry import trace
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk import trace as trace_sdk
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from llama_index.core import VectorStoreIndex, SimpleDirectoryReader

# Initialize OpenTelemetry
tracer_provider = trace_sdk.TracerProvider()
tracer_provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter(
    endpoint="https://router.toqan.ai/eu/v2/otel/v1/traces",
    headers={"Authorization": "Bearer <TOQAN_API_KEY>"}
)))
trace.set_tracer_provider(tracer_provider)

# Instrument LlamaIndex
LlamaIndexInstrumentor().instrument(tracer_provider=tracer_provider)

# Your LlamaIndex code is automatically traced
documents = SimpleDirectoryReader("./data").load_data()
index = VectorStoreIndex.from_documents(documents)

query_engine = index.as_query_engine()
response = query_engine.query("What is the main topic of these documents?")
```

### Visualizar traces

Visualize seus traces no [AI Studio](/docs/pt-BR/ai-studio/observability/quickstart.md), na aba **Traces**.

> [!NOTE]
>
> Acesse seu [AI Studio](https://router.toqan.ai/eu) para ver análises e traces em tempo real.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.