Configure um provedor compatível com OpenAI no Cline para responder a perguntas sobre documentos com fontes

Configure o Cline para responder a perguntas sobre documentos — não apenas para acessar um modelo

Se você quer que um agente de programação responda a perguntas sobre documentos do projeto e indique a origem de cada resposta, há duas tarefas distintas: conectar o Cline a um endpoint de modelo e criar, em torno dessa conexão, um fluxo de recuperação e atribuição de fontes. A documentação do SDK do Cline aborda credenciais do provedor, IDs de modelo e o gateway de LLM. Ela não documenta uma função integrada de busca em documentos ou de citação. Consulte a documentação de provedores de modelo do Cline.

As instruções abaixo são para desenvolvedores que usam o SDK do Cline. Elas não explicam, passo a passo, como configurar a extensão desktop do Cline ou outra interface: a fonte fornecida não confirma essas configurações. Para o SDK, o Cline documenta um provedor openai-compatible com chave de API, URL base e ID do modelo. O OneMux pode ser uma opção prática para acessar modelos por meio de uma API compatível com OpenAI, mas a compatibilidade com um fluxo específico do Cline depende do endpoint e dos recursos de solicitação usados.

Pré-requisitos

Antes de configurar o agente, reúna:

• Um projeto que use o SDK do Cline e os pacotes de provedor relevantes, como @cline/agents. O Cline informa que @cline/agents e @cline/core usam internamente sua camada de LLM; consulte a documentação dos pacotes para saber quais importações e qual formato de construtor correspondem à sua versão.
• Uma chave de API do provedor que você pretende usar, armazenada fora do controle de versão do código-fonte.
• A URL base compatível com OpenAI do provedor e o ID exato do modelo aceito por ele.
• Documentos disponíveis para sua aplicação, além de um método de recuperação que encontre trechos relevantes e preserve os metadados das fontes.

Para configurar a conta e a API do OneMux, comece pelo guia de início rápido do OneMux e pela documentação da API. Antes de usar os valores, confira na documentação o endpoint e o identificador de modelo atuais: este artigo não afirma que algum modelo, endpoint ou integração com o Cline específico tenha sido testado.

Configure o provedor compatível com OpenAI

O padrão de configuração de provedor documentado pelo Cline é:

const agent = new Agent({
  providerId: "openai-compatible",
  modelId: process.env.MODEL_ID,
  apiKey: process.env.PROVIDER_API_KEY,
  baseUrl: process.env.PROVIDER_BASE_URL,
})

Os símbolos Agent e as importações dos pacotes foram omitidos porque a referência fornecida sobre provedores não os especifica. Use as importações e quaisquer opções adicionais exigidas na documentação da versão instalada no seu projeto. Defina MODEL_ID, PROVIDER_API_KEY e PROVIDER_BASE_URL no ambiente local ou no gerenciador de segredos. Esses são nomes de variáveis de ambiente usados como exemplo na aplicação, não nomes exigidos pelo Cline. As variáveis comuns documentadas pelo Cline para OpenAI e outros provedores identificados pelo nome não estabelecem um nome padrão para todos os serviços compatíveis com OpenAI.

Para usar o OneMux, consulte a documentação da API e obtenha a URL base, a chave e o ID do modelo atuais. Informe esses valores nos campos correspondentes. Não presuma que todos os endpoints compatíveis com OpenAI aceitem todos os parâmetros ou recursos opcionais. Confirme o formato das solicitações, o método de autenticação e a disponibilidade do modelo segundo a documentação do endpoint. Em particular, a compatibilidade depende de o provedor aceitar os parâmetros enviados pelo agente.

Adicione atribuição de fontes às respostas sobre documentos

Conectar um modelo não faz com que ele pesquise seus arquivos ou cite fontes. Esse comportamento precisa ser implementado na camada da aplicação:

1. Indexe os documentos com identificadores estáveis. Armazene um ID da fonte, o título do documento e a página, seção ou outra localização de cada trecho recuperável. Mantenha esses metadados junto ao texto.
2. Recupere os trechos antes de fazer a pergunta. Pesquise os trechos relevantes para a pergunta do usuário e inclua uma seleção concisa como contexto. A implementação da busca e o armazenamento de documentos não fazem parte da configuração do provedor descrita pela fonte do Cline.
3. Exija referências na resposta. Peça ao modelo que responda apenas com base nos trechos fornecidos e que retorne referências usando os IDs e as localizações informados. Por exemplo, solicite uma resposta concisa seguida de uma lista de IDs de citação.
4. Valide as citações no código. Confira se todos os IDs retornados existem no conjunto recuperado e gere links ou rótulos a partir dos seus próprios metadados. Se nenhum trecho sustentar a resposta, instrua o fluxo a dizer que os documentos não permitem estabelecê-la, em vez de apresentar uma afirmação sem citação.

Um exemplo de prompt para a etapa de recuperação:

Answer the question using only the supplied document passages.
For each factual claim, cite the passage ID and location in brackets.
If the passages do not support an answer, say so.

Question: {{question}}
Passages:
{{retrieved_passages_with_ids_and_locations}}

Esse é um padrão implementado na aplicação, não uma API de citações documentada pelo Cline. O modelo pode gerar uma referência aparentemente plausível, mas incorreta; por isso, valide-a em relação aos metadados recuperados e, quando necessário, ao texto citado. Para respostas de alto impacto, peça a uma pessoa que revise a resposta e o trecho que a fundamenta.

O que verificar e como solucionar problemas

Falha na autenticação: confira se a chave está disponível no ambiente do processo, se pertence ao serviço configurado e se o endpoint espera o método de autenticação usado pelo cliente. Evite imprimir segredos nos logs.

Modelo não encontrado: confirme o ID exato do modelo com o provedor. A referência do Cline usa um ID específico do provedor; ela não garante que um determinado ID esteja disponível em todos os serviços compatíveis.

As solicitações falham apesar de o endpoint ser identificado como compatível com OpenAI: verifique a URL base, inclusive se o provedor espera um caminho de versão como /v1. Em seguida, compare os parâmetros de solicitação e o formato de resposta usados pela versão instalada do Cline com o suporte descrito na documentação do endpoint. A fonte do Cline fornecida não lista um conjunto universal de parâmetros aceitos por endpoints de terceiros.

As respostas não apresentam fontes confiáveis: confirme que a recuperação encontrou trechos relevantes, que cada trecho tem um identificador e uma localização estáveis e que a aplicação valida as referências retornadas. Configurar o provedor não corrige metadados de recuperação ausentes ou incorretos.

A camada de provedores de modelo do Cline também expõe um gateway e metadados do modelo, incluindo campos como janela de contexto, quantidade máxima de tokens, preços e recursos. A fonte observa que o uso de tokens e os custos podem aparecer nos resultados do agente e nos eventos de uso, mas não estabelece que todos os provedores compatíveis exponham todos os campos de metadados. Consulte a referência de provedores do Cline para ver os detalhes documentados do gateway.

Esta configuração é a opção certa?

Use esta abordagem quando seu agente de programação precisar consultar a documentação do projeto e você puder implementar a recuperação e a validação de citações na própria aplicação. Assim, o acesso ao modelo fica separado dos recursos que tornam as respostas auditáveis. Não é uma função pronta para perguntas e respostas sobre documentos, e a página do Cline citada não confirma uma integração específica com o OneMux nem a atribuição de citações a documentos.

Como próximo passo, configure o endpoint com os valores indicados pelo provedor, teste uma solicitação simples e, depois, implemente a recuperação e a validação das citações em etapas separadas. Consulte as opções disponíveis na página de modelos do OneMux e veja os preços do OneMux para conhecer os custos atuais da conta. Este tutorial não compara preços nem desempenho.

Perguntas frequentes

O provedor compatível com OpenAI do Cline cita documentos automaticamente?

Não. A documentação de provedores do Cline fornecida não confirma esse recurso. Ela descreve a configuração do provedor e os recursos do gateway. Sua aplicação precisa recuperar os documentos, fornecer os metadados das fontes, solicitar referências e validá-las.

Posso usar o OneMux com o Cline?

A documentação do SDK do Cline descreve um provedor openai-compatible. O OneMux permite acessar modelos por meio de uma API compatível com OpenAI. O funcionamento de uma configuração específica depende do endpoint atual, do ID do modelo, da autenticação e dos parâmetros de solicitação; este artigo não afirma que a integração tenha sido testada.

Esta configuração é para a extensão de edição do Cline?

A fonte citada trata dos provedores de modelo do SDK do Cline. Ela não confirma como configurar um provedor na extensão de edição do Cline ou em outras interfaces. Siga a documentação do produto e da versão específica do Cline que você usa.

Como o agente deve responder quando nenhuma fonte sustenta uma resposta?

Instrua-o a dizer que os documentos fornecidos não permitem estabelecer a resposta e valide as citações com base nos trechos recuperados pela aplicação. Não considere uma citação gerada pelo modelo como prova de que o material referenciado sustenta a afirmação.

Fontes

• SDK do Cline: provedores de modelo — configuração de provedores, configuração compatível com OpenAI, gateway, metadados de modelo e informações de uso.