> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apimart.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Usando o APIMart no Dify
> Guia detalhado sobre como configurar e usar o serviço de API do APIMart na plataforma LLMOps Dify. Este guia ajudará você a configurar a API do APIMart no Dify para construir aplicações de IA poderosas.
## Pré-requisitos
Antes de começar, certifique-se de:
1. **Conta no Dify registrada**
Visite o [site oficial do Dify](https://dify.ai/) para registrar uma conta, escolha a versão na nuvem ou auto-hospedada
2. **Chave de API do APIMart obtida**
Acesse o [Console do APIMart](https://apimart.ai/keys) para obter sua chave de API (começa com `sk-`)
**Dica:** Se você ainda não tem uma conta no APIMart, registre-se primeiro em [APIMart](https://apimart.ai) e obtenha uma chave de API.
## Etapa 1: Fazer login no Dify e acessar as configurações
### 1.1 Acessar a plataforma Dify
* **Versão na nuvem:** Visite [https://cloud.dify.ai](https://cloud.dify.ai) e faça login
* **Versão auto-hospedada:** Visite o endereço da sua implantação do Dify
*Interface principal do Dify mostrando a lista de aplicações e o botão de criar aplicativo*
### 1.2 Navegar até as configurações de modelos
1. Clique no **ícone de avatar** no canto superior direito
2. Selecione **Settings**
3. Escolha **Model Provider** no menu à esquerda
*Encontre a opção "Model Provider" no menu à esquerda*
**Nota:** O Dify suporta a configuração de vários provedores de modelos. Você pode usar o APIMart ao lado de outros provedores.
## Etapa 2: Adicionar o provedor de modelos APIMart
**Métodos de configuração:** Há duas maneiras de configurar o APIMart no Dify:
**Método 1 (Recomendado):** Use o recurso de API personalizada do provedor OpenAI
* Nas configurações do provedor OpenAI, modifique diretamente a Base URL para `https://api.apimart.ai/v1`
* Insira sua chave de API do APIMart
* Configuração mais rápida e simples
**Método 2:** Adicionar como provedor de modelo personalizado (Método deste guia)
* Mais flexível, pode gerenciar o provedor APIMart separadamente
* Conveniente para usar vários provedores de API simultaneamente
Ambos os métodos são funcionalmente idênticos. Escolha com base na sua preferência.
### 2.1 Selecionar o método de configuração
#### Método 1: Usar a API personalizada da OpenAI (Recomendado)
1. Encontre o provedor **OpenAI** na página Model Provider
2. Clique no botão **Configure** ou **Settings**
3. Na página de configuração:
* **API Key**: Insira sua chave de API do APIMart (`sk-xxxxxxxxxxxx`)
* **API Base URL** ou **Base URL**: Insira `https://api.apimart.ai/v1`
4. Clique em **Save**
*Configure a API Key e Base URL do APIMart no provedor OpenAI*
5. Após a configuração, retorne à página do provedor OpenAI e visualize a **Model List**
6. Na lista de modelos, encontre os modelos que você precisa (por exemplo, `gpt-4o`, `gpt-4o-mini`, `chatgpt-4o-latest`, etc.)
7. Clique no **interruptor** no lado direito do modelo para ativá-lo (azul indica ativado)
*Ative os modelos que você precisa na lista de modelos do OpenAI*
**Importante:** Apenas ative os modelos realmente suportados pelo APIMart!
Embora a lista de modelos OpenAI do Dify exiba muitos modelos, apenas aqueles suportados pelo APIMart funcionarão corretamente. Ativar modelos não suportados causará falhas nas chamadas de API.
Consulte a [Documentação da API do APIMart](https://docs.apimart.ai) para a lista completa de modelos suportados.
**Modelos suportados e recomendados pelo APIMart:**
**Série GPT:**
* `gpt-5` / `gpt-5-chat-latest` - Modelos da série GPT-5
* `chatgpt-4o-latest` / `gpt-4o` - Modelo GPT-4o mais recente
* `gpt-4o-mini` - Versão rápida e econômica
* `gpt-4.1` / `gpt-4.1-mini` - Série GPT-4.1
**Série Claude:**
* `claude-sonnet-4-5-20250929` - Claude Sonnet 4.5
* `claude-haiku-4-5-20251001` - Claude Haiku 4.5
**Série Gemini:**
* `gemini-2.0-flash-exp` - Google Gemini 2.0 Flash
Você pode ativar vários modelos simultaneamente e alternar entre eles de forma flexível em suas aplicações.
Após a conclusão, você pode usá-lo diretamente. Pule para a **Etapa 3**.
#### Método 2: Adicionar provedor de modelo personalizado
Na página Model Provider:
1. Role para baixo até a seção **Custom Model**
2. Clique no botão **+ Add Model**
*Role até a seção de modelos personalizados e clique no botão "+ Add Model"*
### 2.2 Configurar o provedor APIMart
No diálogo de configuração, preencha as seguintes informações:
| Campo | Valor |
| ----------------------- | ------------------------------------------------------------------------------------------------------------- |
| **Model Name** | `APIMart` ou nome personalizado |
| **Model Type** | Selecione `LLM` (Large Language Model) |
| **API Key** | Sua chave de API do APIMart (`sk-xxxxxxxxxxxx`) |
| **API endpoint URL** | `https://api.apimart.ai/v1` |
| **Endpoint model name** | Insira o nome específico do modelo (por exemplo, `gpt-4o`, `gpt-4o-mini`, `claude-sonnet-4-5-20250929`, etc.) |
*Preencha a configuração do provedor APIMart*
**Importante:**
* A Base URL deve incluir o sufixo `/v1`: `https://api.apimart.ai/v1`
* A API Key deve ser obtida no console do APIMart e começar com `sk-`
* Verifique se sua chave de API possui saldo suficiente
### 2.3 Adicionar mais modelos (opcional)
Para adicionar mais modelos, repita as etapas acima:
1. Na seção de modelos personalizados, clique novamente no botão **+ Add Model**
2. Preencha as informações de configuração para outro modelo
3. Clique em Salvar
*Repita as etapas de adição de modelo para configurar vários modelos diferentes*
**Modelos recomendados para adicionar:**
#### Série GPT-4/5
| ID do modelo | Nome do modelo | Comprimento do contexto | Caso de uso |
| ------------- | -------------- | ----------------------- | ----------------------------------------------- |
| `gpt-5` | GPT-5 | 128.000 | Tarefas complexas, processamento de texto longo |
| `gpt-4o` | GPT-4o | 128.000 | Chat de alta qualidade, geração de código |
| `gpt-4o-mini` | GPT-4o Mini | 128.000 | Resposta rápida, custo-benefício |
#### Série Claude
| ID do modelo | Nome do modelo | Comprimento do contexto | Caso de uso |
| ---------------------------- | ----------------- | ----------------------- | -------------------------------------- |
| `claude-sonnet-4-5-20250929` | Claude Sonnet 4.5 | 200.000 | Raciocínio complexo, análise de código |
| `claude-haiku-4-5-20251001` | Claude Haiku 4.5 | 200.000 | Resposta rápida, tarefas simples |
#### Série Gemini
| ID do modelo | Nome do modelo | Comprimento do contexto | Caso de uso |
| ---------------------- | ---------------- | ----------------------- | ------------------------------------ |
| `gemini-2.0-flash-exp` | Gemini 2.0 Flash | 32.000 | Multimodal, aplicações em tempo real |
**Recomendações de desempenho:**
* 💰 **Custo-benefício:** `gpt-4o-mini`, `claude-haiku-4-5-20251001`
* 🚀 **Alto desempenho:** `gpt-5`, `gpt-4o`, `claude-sonnet-4-5-20250929`
* ⚡ **Resposta rápida:** `gemini-2.0-flash-exp`, `gpt-4o-mini`
## Etapa 3: Usar os modelos do APIMart em aplicações
### 3.1 Criar nova aplicação
1. Volte para a página inicial do Dify
2. Clique no botão **Create App**
3. Selecione o tipo de aplicação:
* **Chatbot** - Aplicação de conversação
* **Text Generator** - Aplicação de geração de texto
* **Agent** - Agente inteligente
* **Workflow** - Aplicação de fluxo de trabalho complexo
*Selecione o tipo de aplicação para criar um novo app*
### 3.2 Selecionar modelo APIMart
Na página de orquestração da aplicação:
1. Encontre a área **Model Settings**
2. Clique no menu suspenso **Select Model**
3. Selecione o provedor **APIMart**
4. Escolha seu modelo configurado (por exemplo, `gpt-4o`)
*Selecione o modelo do provedor APIMart na aplicação*
### 3.3 Configurar parâmetros do modelo
Ajuste os parâmetros do modelo conforme necessário:
| Parâmetro | Descrição | Valor recomendado |
| --------------------- | --------------------------------- | ------------------------------ |
| **Temperature** | Controla a aleatoriedade da saída | 0.7 (criativo) / 0.3 (preciso) |
| **Max Tokens** | Comprimento máximo da saída | 2000-4000 |
| **Top P** | Parâmetro de amostragem nuclear | 0.9 |
| **Presence Penalty** | Reduz repetição | 0.0-0.5 |
| **Frequency Penalty** | Reduz palavras frequentes | 0.0-0.5 |
*Ajuste os parâmetros do modelo com base nas necessidades da aplicação*
## Etapa 4: Construir e testar a aplicação
### 4.1 Adicionar prompts
Na página de orquestração da aplicação:
1. Escreva prompts na área **System Prompt**
2. Use variáveis para tornar seu app dinâmico:
* `{{variable_name}}` - Variável de entrada do usuário
* `{{context}}` - Contexto da base de conhecimento
**Exemplo de prompt:**
```
You are a professional customer service assistant, skilled at answering product questions.
Product Information: {{product_info}}
Please provide accurate and friendly answers based on user questions. If unsure, honestly inform the user.
User Question: {{user_question}}
```
*Escreva e configure prompts no editor de prompts*
### 4.2 Adicionar base de conhecimento (opcional)
Se você precisar de capacidade RAG (Retrieval Augmented Generation):
1. Clique em **Knowledge Base** no menu à esquerda
2. Crie uma nova base de conhecimento e faça upload de documentos
3. Vincule a base de conhecimento na página de orquestração da aplicação
4. Configure os parâmetros de recuperação
### 4.3 Testar a aplicação
1. Digite perguntas de teste no painel **Preview** à direita
2. Revise a eficácia da resposta da IA
3. Ajuste prompts e parâmetros conforme necessário
4. Repita o teste até ficar satisfeito
*Teste a eficácia da aplicação no painel de visualização*
### 4.4 Publicar a aplicação
Após o teste:
1. Clique no botão **Publish** no canto superior direito
2. Selecione o método de publicação:
* **API Call** - Integração via API
* **Embed in Website** - Gerar código de incorporação
* **Public Link** - Gerar link de compartilhamento
*Selecione o método de publicação apropriado*
## Etapa 5: Monitorar e otimizar
### 5.1 Visualizar logs da aplicação
Na página de detalhes da aplicação:
1. Clique na aba **Logs**
2. Visualize todos os registros de conversa
3. Analise as perguntas dos usuários e as respostas da IA
4. Descubra oportunidades de melhoria
*Visualize e analise os logs de uso da aplicação*
### 5.2 Monitorar o uso da API
Acesse o [Console do APIMart](https://apimart.ai/overview) para visualizar:
* 📊 **Estatísticas de chamadas de API** - Total de chamadas, taxa de sucesso
* 💰 **Detalhes de custos** - Custos diários/mensais
* 📈 **Tendências de uso** - Tendências de mudança de uso
* 🔍 **Logs de requisições** - Registros detalhados de requisições
### 5.3 Otimizar o desempenho da aplicação
Otimize com base nos dados de monitoramento:
1. **Ajustar a seleção de modelos**
* Use `gpt-4o-mini` para tarefas simples para reduzir custos
* Use `gpt-4o` ou `claude-sonnet-4-5` para tarefas complexas para melhorar a qualidade
2. **Otimizar prompts**
* Torne os prompts mais claros e específicos
* Adicione exemplos para melhorar a eficácia
* Use cadeia de pensamento para melhor raciocínio
3. **Configurar caching**
* Ative o cache para perguntas similares
* Reduza os custos de chamadas de API
## Recursos avançados
### Usando orquestração de fluxo de trabalho
O recurso de fluxo de trabalho do Dify permite que você:
1. **Branches condicionais** - Execute lógica diferente com base nas condições
2. **Colaboração multimodelo** - Combine vantagens de vários modelos
3. **Chamadas a ferramentas externas** - Chame APIs, bancos de dados e outros recursos externos
4. **Passagem de variáveis** - Passe dados entre diferentes nós
### Configurando capacidades de Agente
Construa agentes inteligentes com modelos do APIMart:
1. **Chamada de ferramentas** - Deixe a IA chamar ferramentas externas
2. **Gerenciamento de memória** - Mantenha memória de conversa de longo prazo
3. **Tomada de decisão autônoma** - A IA planeja autonomamente os passos de execução
### Aplicações multimodais
Aproveite as capacidades multimodais do APIMart:
1. **Compreensão de imagens** - Use `gpt-4o` ou `claude-3` para processar imagens
2. **Geração de imagens** - Integre a API de geração de imagens do APIMart
3. **Processamento de voz** - Integre serviços TTS e STT
## FAQ
### Q1: Não consigo me conectar ao serviço APIMart?
**Solução:**
1. **Verifique a Base URL**:
* Certifique-se de que seja `https://api.apimart.ai/v1` (inclui `/v1`)
* Não adicione caminhos extras ou omita `/v1`
2. **Verifique a API Key**:
* Confirme que a API Key começa com `sk-`
* Verifique se a chave é válida no [Console do APIMart](https://apimart.ai/keys)
3. **Verifique a conexão de rede**:
* Certifique-se de que o servidor pode acessar `https://api.apimart.ai`
* Versões auto-hospedadas precisam garantir a conectividade de rede do servidor
### Q2: A resposta do modelo está lenta?
**Solução:**
1. **Mude para modelos mais rápidos**:
* Use `gpt-4o-mini` em vez de `gpt-4o`
* Use `gemini-2.0-flash-exp` para resposta mais rápida
2. **Otimize o comprimento do prompt**:
* Reduza contexto desnecessário
* Simplifique as descrições dos prompts
3. **Ajuste a recuperação da base de conhecimento**:
* Reduza o número de documentos recuperados
* Aumente o limite de similaridade
### Q3: Chamadas de API falham ou retornam erros?
**Erros comuns e soluções:**
| Mensagem de erro | Causa | Solução |
| --------------------------- | ---------------------------------------- | --------------------------------------------------------------------------- |
| `401 Unauthorized` | API Key inválida ou expirada | Obtenha a API Key novamente e atualize a configuração |
| `429 Too Many Requests` | Limite de taxa de requisições excedido | Ajuste as configurações de concorrência do app ou aguarde e tente novamente |
| `500 Internal Server Error` | Problema temporário no servidor | Aguarde alguns minutos e tente novamente |
| `insufficient_quota` | Saldo insuficiente na conta | Recarregue no console |
| `context_length_exceeded` | Entrada excede o comprimento do contexto | Reduza o comprimento da entrada ou use um modelo com contexto maior |
### Q4: Como reduzir os custos de uso da API?
**Sugestões de otimização de custos:**
1. **Seleção de modelos**:
* Use `gpt-4o-mini` para tarefas simples (custo é apenas 1/10 do `gpt-4o`)
* Considere modelos mais econômicos para tarefas em lote
2. **Ative caching**:
* Retorne resultados em cache para as mesmas perguntas
* Configure a correspondência de similaridade no Dify
3. **Otimize o comprimento da saída**:
* Defina um Max Tokens razoável
* Evite gerar respostas excessivamente longas
4. **Use saída em streaming**:
* Melhore a experiência do usuário sem aumentar os custos
### Q5: Como lidar com dados sensíveis?
**Recomendações de segurança de dados:**
1. **Use variáveis de ambiente**:
* Não codifique chaves de API no código
* Use o recurso de variáveis de ambiente do Dify
2. **Configure controle de acesso**:
* Defina permissões de acesso à aplicação
* Ative autenticação para chamadas de API
3. **Logs de auditoria**:
* Verifique regularmente os logs da aplicação
* Monitore padrões de acesso anormais
## Melhores práticas
### 1. Engenharia de prompts
**Prompts estruturados:**
```
# Role Definition
You are a professional [role description]
# Task Objective
You need to help users [task description]
# Output Requirements
- Requirement 1
- Requirement 2
- Requirement 3
# Input Information
{{user_input}}
```
### 2. Gerenciamento da base de conhecimento
* **Estratégia de divisão**: Defina um tamanho razoável de pedaço de documento (recomendado 500-1000 caracteres)
* **Marcação de metadados**: Adicione metadados aos documentos para facilitar a recuperação
* **Atualizações regulares**: Mantenha o conteúdo da base de conhecimento atualizado
### 3. Tratamento de erros
* **Mensagens amigáveis**: Forneça mensagens de erro claras aos usuários
* **Estratégia de fallback**: Mude para um modelo de backup quando o principal falhar
* **Mecanismo de retentativa**: Retentativa automática para erros temporários
### 4. Monitoramento de desempenho
* **Defina alertas**: Alerte para saldo baixo, altas taxas de erro
* **Análise regular**: Analise os dados de uso semanal/mensalmente
* **Otimização contínua**: Ajuste a configuração com base nos dados
## Exemplos de casos de uso
### 1. Atendimento ao cliente inteligente
**Configuração da aplicação:**
* Modelo: `gpt-4o-mini` (custo-benefício)
* Base de conhecimento: Documentos de produto, FAQ
* Recursos: Respostas automáticas a perguntas comuns, escala problemas complexos para humanos
### 2. Assistente de criação de conteúdo
**Configuração da aplicação:**
* Modelo: `gpt-4o` ou `claude-sonnet-4-5` (alta qualidade)
* Recursos: Geração de artigos, reescrita, polimento
* Parâmetros: Temperature=0.8 (aumentar criatividade)
### 3. Assistente de código
**Configuração da aplicação:**
* Modelo: `claude-sonnet-4-5` (excelente para código)
* Recursos: Geração, explicação, depuração de código
* Base de conhecimento: Documentação do projeto, documentação da API
### 4. Assistente de análise de dados
**Configuração da aplicação:**
* Modelo: `gpt-4o` (forte capacidade de raciocínio)
* Ferramentas: Execução de código Python, visualização de dados
* Recursos: Análise de dados, geração de relatórios
## Recursos
Usando Dify + APIMart, você pode:
* 🤖 **Construir aplicações de IA rapidamente** - Crie aplicações de IA poderosas sem codificação
* 📚 **Aprimoramento com base de conhecimento** - A tecnologia RAG permite que a IA responda com base em seus dados
* 🔧 **Fluxos de trabalho flexíveis** - Orquestre visualmente lógica de IA complexa
* 🎯 **Gerenciamento preciso de prompts** - Controle de versão e teste A/B
* 📊 **Monitoramento e análise completos** - Entenda o uso e desempenho do app
* 🔌 **Múltiplos métodos de integração** - API, incorporado, WebApp e mais
* 👥 **Colaboração em equipe** - Suporte ao desenvolvimento colaborativo multiusuário
* 🌐 **Suporte multimodelo** - Alterne flexivelmente entre diferentes modelos de IA
## Suporte e ajuda
Se você encontrar algum problema:
* 📚 [Documentação do APIMart](https://docs.apimart.ai)
* 📚 [Documentação oficial do Dify](https://docs.dify.ai)
* 💬 [Comunidade do Discord](https://discord.gg/V8zqssyZ5c)
* 🐦 [Twitter @APIMart\_](https://x.com/APIMart_)
* 📧 Suporte técnico: [zhihong@apimart.ai](mailto:zhihong@apimart.ai)
***
Registre-se no APIMart agora, obtenha sua chave de API e construa aplicações de IA poderosas no Dify!