> ## 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 DSPy

> Integre o DSPy ao AI Gateway para programas de LLM otimizados. Use o framework de Stanford para otimização automática de prompts e sistemas de IA baseados em raciocínio.

> [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 DSPy é um framework para otimizar programaticamente prompts e pesos de LLMs por meio de módulos e signatures combináveis. Ao conectar o DSPy ao AI Gateway do Toqan Router, você tem acesso a mais de 500 modelos para seus pipelines de otimização de prompts com uma única alteração de configuração.

### Principais benefícios

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

> [card] Observabilidade completa
>
> Acompanhe cada execução de signature, chamada de módulo e etapa de otimização

> [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 DSPy ao Toqan Router, certifique-se de ter:

* Uma conta no Toqan Router e uma chave de API
* Python 3.8 ou superior

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

### Instalação

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
pip install dspy
```

### Configuração

Configure o DSPy para usar o AI Gateway do Toqan Router com `dspy.LM`:

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import dspy
import os

lm = dspy.LM(
    "openai/openai/gpt-5.6-sol",
    api_key=os.getenv("TOQAN_API_KEY"),
    api_base="https://router.toqan.ai/eu/v3/router",
)
dspy.configure(lm=lm)
```

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

> [!WARNING]
>
> O DSPy exige prefixo duplo no nome do modelo ao usar um `api_base` personalizado. Adicione `openai/` antes do identificador do modelo: `gpt-5.6-sol` → `openai/openai/gpt-5.6-sol`

### Exemplo básico

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import dspy
import os

lm = dspy.LM(
    "openai/openai/gpt-5.6-sol",
    api_key=os.getenv("TOQAN_API_KEY"),
    api_base="https://router.toqan.ai/eu/v3/router",
)
dspy.configure(lm=lm)

class BasicQA(dspy.Signature):
    """Answer questions with short, accurate responses."""
    question: str = dspy.InputField()
    answer: str = dspy.OutputField()

qa = dspy.Predict(BasicQA)
result = qa(question="What is the capital of France?")
print(result.answer)
```

### Chain of Thought

Use `ChainOfThought` para raciocínio passo a passo:

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import dspy
import os

lm = dspy.LM(
    "openai/openai/gpt-5.6-sol",
    api_key=os.getenv("TOQAN_API_KEY"),
    api_base="https://router.toqan.ai/eu/v3/router",
)
dspy.configure(lm=lm)

class MathProblem(dspy.Signature):
    """Solve math problems step by step."""
    problem: str = dspy.InputField()
    answer: str = dspy.OutputField()

cot = dspy.ChainOfThought(MathProblem)
result = cot(problem="If a train travels 120 miles in 2 hours, what is its speed?")
print(result.answer)
```

### Seleção de modelo

Com o Toqan Router, você pode usar qualquer modelo compatível de mais de 30 provedores. O `openai/` inicial não faz parte do nome do modelo: ele indica ao cliente LiteLLM do DSPy que use o protocolo OpenAI para se comunicar com o router, seguido do identificador `provider/model` do Toqan Router (veja o aviso acima):

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import dspy
import os

# Use Claude ("openai/" LiteLLM prefix + Toqan Router model id "anthropic/claude-sonnet-5")
claude_lm = dspy.LM(
    "openai/anthropic/claude-sonnet-5",
    api_key=os.getenv("TOQAN_API_KEY"),
    api_base="https://router.toqan.ai/eu/v3/router",
)

# Use Gemini ("openai/" LiteLLM prefix + Toqan Router model id "google/gemini-2.5-flash")
gemini_lm = dspy.LM(
    "openai/google/gemini-2.5-flash",
    api_key=os.getenv("TOQAN_API_KEY"),
    api_base="https://router.toqan.ai/eu/v3/router",
)

class BasicQA(dspy.Signature):
    """Answer questions with short, accurate responses."""
    question: str = dspy.InputField()
    answer: str = dspy.OutputField()

qa = dspy.Predict(BasicQA)

with dspy.context(lm=claude_lm):
    result = qa(question="What is the largest planet?")
    print(result.answer)
```

## Observabilidade

### Primeiros passos

O DSPy de Stanford é um framework para otimizar algoritmicamente prompts e pesos de LMs por meio de programação em vez de prompting. Rastrear o DSPy com o Toqan Router oferece insights abrangentes sobre execução de signatures, desempenho de módulos, processos de otimização e eficácia do aprendizado few-shot, para que você otimize suas aplicações programáticas de LLM.

### Pré-requisitos

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

* Uma conta no Toqan Router e uma chave de API
* Python 3.8+
* O DSPy instalado no seu projeto
* Chaves de API dos provedores de LLM escolhidos

### Instalar dependências

```bash Bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Core DSPy and OpenTelemetry packages
pip install dspy-ai opentelemetry-sdk opentelemetry-exporter-otlp

# OpenInference instrumentation for DSPy
pip install openinference-instrumentation-dspy

# LLM providers
pip install openai
```

### Configurar o Toqan Router

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

**Unix/Linux/macOS:**

```bash 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=dspy-app,service.version=1.0.0"
export OPENAI_API_KEY="<YOUR_OPENAI_API_KEY>"
```

**Windows (PowerShell):**

```bash 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=dspy-app,service.version=1.0.0"
$env:OPENAI_API_KEY = "<YOUR_OPENAI_API_KEY>"
```

**Usando um arquivo .env:**

```bash 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=dspy-app,service.version=1.0.0
OPENAI_API_KEY=<YOUR_OPENAI_API_KEY>
```

### Integração

O DSPy usa a instrumentação OpenInference para tracing automático com OpenTelemetry.

> Configure a instrumentação na sua aplicação:

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from opentelemetry import trace
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
import os

# Configure tracer provider
tracer_provider = TracerProvider(
    resource=Resource({"service.name": "dspy-app"})
)

# Set up OTLP exporter
otlp_exporter = OTLPSpanExporter(
    endpoint=f"{os.getenv('OTEL_EXPORTER_OTLP_ENDPOINT')}/v1/traces",
    headers={"Authorization": os.getenv('OTEL_EXPORTER_OTLP_HEADERS').split('=', 1)[1]}
)

tracer_provider.add_span_processor(BatchSpanProcessor(otlp_exporter))

# Instrument DSPy
from openinference.instrumentation.dspy import DSPyInstrumentor

DSPyInstrumentor().instrument(tracer_provider=tracer_provider)
```

> Use o DSPy com tracing automático:

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import dspy
from opentelemetry import trace
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
import os

# Configure OpenTelemetry
tracer_provider = TracerProvider(
    resource=Resource({"service.name": "dspy-app"})
)

otlp_exporter = OTLPSpanExporter(
    endpoint=f"{os.getenv('OTEL_EXPORTER_OTLP_ENDPOINT')}/v1/traces",
    headers={"Authorization": os.getenv('OTEL_EXPORTER_OTLP_HEADERS').split('=', 1)[1]}
)

tracer_provider.add_span_processor(BatchSpanProcessor(otlp_exporter))

# Instrument DSPy
from openinference.instrumentation.dspy import DSPyInstrumentor

DSPyInstrumentor().instrument(tracer_provider=tracer_provider)

# Modern DSPy syntax (v2.0+)
lm = dspy.LM('openai/gpt-5.6-sol', api_key=os.getenv('OPENAI_API_KEY'))
dspy.configure(lm=lm)

# Define signature
class BasicQA(dspy.Signature):
    """Answer questions with helpful and accurate responses"""
    question = dspy.InputField()
    answer = dspy.OutputField(desc="A comprehensive answer to the question")

# Create predictor (automatically traced)
qa = dspy.Predict(BasicQA)

# Execute prediction
result = qa(question="What are the benefits of renewable energy?")
print(result.answer)
```

> [!TIP]
>
> Todas as execuções de signatures e operações de módulos do DSPy serão instrumentadas automaticamente e exportadas para o Toqan Router pelo exporter OTLP. Para mais detalhes, consulte [Traces](/docs/pt-BR/ai-studio/observability/traces.md).

### Exemplos avançados

**Raciocínio com Chain of Thought**

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import dspy

# Setup done as shown in Integration section above

lm = dspy.LM('openai/gpt-5.6-sol', api_key=os.getenv('OPENAI_API_KEY'))
dspy.configure(lm=lm)

# Define signature with reasoning
class ComplexProblem(dspy.Signature):
    """Solve complex problems with step-by-step reasoning"""
    problem = dspy.InputField(desc="The problem to solve")
    reasoning = dspy.OutputField(desc="Step-by-step reasoning process")
    solution = dspy.OutputField(desc="Final solution")

# Use Chain of Thought
class ReasoningModule(dspy.Module):
    def __init__(self):
        super().__init__()
        self.think = dspy.ChainOfThought(ComplexProblem)

    def forward(self, problem):
        return self.think(problem=problem)

# Execute with tracing
reasoner = ReasoningModule()

problems = [
    "A farmer has 17 sheep. All but 9 die. How many are left?",
    "If it takes 5 machines 5 minutes to make 5 widgets, how long for 100 machines to make 100 widgets?"
]

for problem in problems:
    result = reasoner(problem=problem)
    print(f"Problem: {problem}")
    print(f"Reasoning: {result.reasoning}")
    print(f"Solution: {result.solution}\n")
```

**Otimização few-shot**

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import dspy

lm = dspy.LM('openai/gpt-5.6-sol', api_key=os.getenv('OPENAI_API_KEY'))
dspy.configure(lm=lm)

# Define signature
class SentimentAnalysis(dspy.Signature):
    """Analyze sentiment of text"""
    text = dspy.InputField()
    sentiment = dspy.OutputField(desc="positive, negative, or neutral")
    confidence = dspy.OutputField(desc="Confidence score 0-1")

# Create module
class SentimentClassifier(dspy.Module):
    def __init__(self):
        super().__init__()
        self.classify = dspy.ChainOfThought(SentimentAnalysis)

    def forward(self, text):
        return self.classify(text=text)

# Training examples
training_examples = [
    dspy.Example(
        text="I love this product! Amazing quality!",
        sentiment="positive",
        confidence="0.95"
    ).with_inputs("text"),
    dspy.Example(
        text="Terrible experience. Very disappointed.",
        sentiment="negative",
        confidence="0.9"
    ).with_inputs("text"),
    dspy.Example(
        text="It's okay, nothing special.",
        sentiment="neutral",
        confidence="0.8"
    ).with_inputs("text")
]

# Create optimizer (automatically traced)
classifier = SentimentClassifier()

optimizer = dspy.BootstrapFewShot(
    metric=lambda gold, pred, trace=None: gold.sentiment == pred.sentiment,
    max_bootstrapped_demos=3
)

# Compile optimized program
optimized_classifier = optimizer.compile(
    classifier,
    trainset=training_examples
)

# Test
result = optimized_classifier(text="This is fantastic!")
print(f"Sentiment: {result.sentiment}, Confidence: {result.confidence}")
```

**Pipeline de RAG com múltiplas etapas**

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import dspy
from typing import List

lm = dspy.LM('openai/gpt-5.6-sol', api_key=os.getenv('OPENAI_API_KEY'))
dspy.configure(lm=lm)

# Define signatures
class GenerateQuery(dspy.Signature):
    """Generate search query from question"""
    question = dspy.InputField()
    search_query = dspy.OutputField(desc="Optimized search query")

class AnswerWithContext(dspy.Signature):
    """Answer question using context"""
    question = dspy.InputField()
    context = dspy.InputField(desc="Retrieved context")
    answer = dspy.OutputField(desc="Comprehensive answer")
    sources = dspy.OutputField(desc="Sources used")

# Build RAG system
class RAGPipeline(dspy.Module):
    def __init__(self, knowledge_base: List[dict]):
        super().__init__()
        self.knowledge_base = knowledge_base
        self.query_generator = dspy.Predict(GenerateQuery)
        self.answer_generator = dspy.ChainOfThought(AnswerWithContext)

    def retrieve(self, query: str, top_k: int = 3) -> List[str]:
        # Simple keyword matching
        query_words = set(query.lower().split())
        scored = []
        for doc in self.knowledge_base:
            doc_words = set(doc['content'].lower().split())
            score = len(query_words.intersection(doc_words))
            if score > 0:
                scored.append((score, doc))
        scored.sort(reverse=True, key=lambda x: x[0])
        return [doc['content'] for _, doc in scored[:top_k]]

    def forward(self, question):
        # Generate search query
        query_result = self.query_generator(question=question)

        # Retrieve contexts
        contexts = self.retrieve(query_result.search_query)
        context_text = "\n\n".join(contexts)

        # Generate answer
        answer_result = self.answer_generator(
            question=question,
            context=context_text
        )

        return dspy.Prediction(
            query=query_result.search_query,
            answer=answer_result.answer,
            sources=answer_result.sources
        )

# Example knowledge base
kb = [
    {"id": "1", "content": "Machine learning is a subset of AI that enables systems to learn from data."},
    {"id": "2", "content": "Neural networks are computing systems inspired by biological neural networks."},
    {"id": "3", "content": "Natural Language Processing focuses on interaction between computers and human language."}
]

# Use RAG pipeline (automatically traced)
rag = RAGPipeline(kb)
result = rag(question="What is machine learning?")

print(f"Query: {result.query}")
print(f"Answer: {result.answer}")
print(f"Sources: {result.sources}")
```

> [!TIP]
>
> O DSPy também é compatível com nosso [AI Gateway](#ai-gateway). Para saber mais, consulte [DSPy](#ai-gateway).


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