Do OCI Console à primeira configuração do Cline usando a API OpenAI-compatible.

O que você vai aprender neste tutorial

• Criar uma chave de API do OCI Generative AI
• Criar uma política do IAM para autorizar o acesso
• Identificar o endpoint regional OpenAI-compatible
• Selecionar um identificador de modelo compatível no Generative AI Playground
• Configurar o provider no Cline do Visual Studio Code

1. Visão geral da solução

O Cline é uma extensão de terceiros para Visual Studio Code que pode utilizar modelos de linguagem por meio de diferentes provedores. Neste tutorial, ele é configurado para consumir o OCI Generative AI por meio de um endpoint compatível com a API da OpenAI.

Aviso sobre o Cline: o Cline não é um produto da Oracle. Esta configuração é um exemplo técnico e não implica suporte, parceria ou endosso da Oracle. Antes de usar em produção, valide a versão do Cline, a compatibilidade do modelo e os requisitos de segurança do seu ambiente.

O fluxo pode ser resumido em quatro etapas: criar a credencial, autorizar a credencial no IAM, identificar o endpoint/modelo e configurar o Cline.

2. Pré-requisitos

Antes de iniciar, confirme que você possui acesso ao Oracle Cloud Infrastructure e autorização para criar uma chave de API do OCI Generative AI e uma política do IAM no compartment escolhido. Escolha uma região em que o modelo pretendido esteja disponível: a chave de API e o modelo precisam ser compatíveis com a mesma região. Também é necessário ter o Visual Studio Code e a extensão Cline instalados.

• Conta e acesso ao Oracle Cloud Infrastructure
• Permissões para criar chaves de API e políticas do IAM
• Compartment e região nos quais a solução será usada
• Visual Studio Code instalado
• Extensão Cline instalada

3. Criando a chave de API do OCI Generative AI

A primeira etapa é criar a credencial que o Cline utilizará para autenticar as chamadas ao OCI Generative AI. No console do OCI, acesse a área do serviço Generative AI e abra a opção de criação de chaves de API.

Preencha o nome e a descrição da chave, selecione o compartment adequado e, quando aplicável, defina a validade da credencial. Uma expiração explícita reduz o tempo de exposição de uma credencial de desenvolvimento.

4. Criando a política do IAM

A chave de API identifica o chamador, mas ainda precisamos autorizar esse chamador a utilizar o serviço. Para isso, crie uma política do IAM no compartment apropriado.

Na tela de políticas, escolha o compartment que receberá a regra e selecione Create Policy. Dê à política um nome que deixe clara sua finalidade, como “AI-Cline-Access”.

A regra segue este conceito: permitir que uma identidade do tipo chave de API do OCI Generative AI utilize o recurso de chat no compartment selecionado, condicionando o acesso ao OCID específico da chave.

Substitua <COMPARTMENT> pelo compartment correto e <GENERATIVE_AI_API_KEY_OCID> pelo OCID da chave criada no passo anterior. Revise a regra antes de criar a política do IAM.

5. Identificando a Base URL compatível com OpenAI

Com a autenticação e a autorização configuradas, precisamos informar ao Cline o endpoint regional que expõe a interface compatível com a API da OpenAI.

Neste tutorial, que usa uma chave de API do OCI Generative AI, o padrão de Base URL é:

Exemplo, a região é US East (Ashburn), resultando em:

Use essa URL como Base URL no Cline. Substitua <region> pelo identificador da região escolhida; não acrescente /chat/completions, pois o cliente inclui o caminho da operação.

O OCI também disponibiliza a estrutura /openai/v1 para endpoints compatíveis com OpenAI em outros fluxos. As duas estruturas não devem ser concatenadas nem alternadas sem validar o cenário, o modelo e a versão do cliente. Para este tutorial, mantenha /20231130/actions/v1 com a chave de API do OCI Generative AI.

Consulte a documentação de endpoints compatíveis com OpenAI do OCI para entender os recursos e caminhos suportados em cada fluxo.

6. Configurando o Cline no Visual Studio Code

Abra o Cline no Visual Studio Code e acesse Settings → API Configuration. No campo API Provider, selecione OpenAI Compatible.

Preencha os campos de acordo com a configuração criada no OCI. Os nomes em inglês abaixo correspondem aos rótulos exibidos na interface do Cline:

7. Encontrando o identificador do modelo

O identificador do modelo pode ser obtido no Generative AI Playground. No console do OCI, abra Analytics & AI → Playground → Chat, selecione o compartment e abra a lista de modelos disponíveis.

A lista pode conter modelos de diferentes famílias. Escolha um modelo compatível e disponível na região selecionada e copie o identificador exatamente como apresentado no console. A disponibilidade, o modo de acesso e a compatibilidade com endpoints podem variar por região e mudar ao longo do tempo.

Consulte a documentação de modelos e regiões do OCI Generative AI e confirme também a disponibilidade da chave de API na região pretendida.

A documentação de chaves de API do OCI Generative AI explica os requisitos regionais e as práticas recomendadas para armazenar e rotacionar a credencial.

8. Validando a configuração

Depois de preencher o provider, a Base URL, a chave de API e o identificador do modelo, conclua a configuração no Cline e inicie uma interação simples para validar o acesso.

Uma validação prática consiste em enviar uma solicitação curta e verificar se o Cline consegue processá-la sem retornar erro de autenticação, endpoint ou modelo. Caso a chamada falhe, volte às etapas de política do IAM, Base URL, região e identificador do modelo antes de alterar outros parâmetros.

9. Problemas comuns e diagnóstico

10. Conclusão

A integração do Cline com o OCI Generative AI pode ser realizada sem uma implementação específica do SDK do OCI. O ponto central é utilizar o endpoint compatível com OpenAI, combinado com uma chave de API autorizada por uma política do IAM e com um identificador de modelo disponível na mesma região.

O fluxo completo é simples de repetir: criar a credencial, conceder o acesso mínimo necessário, identificar o endpoint e o modelo compatíveis com a região, e então configurar esses valores no Cline. A partir daí, o Visual Studio Code passa a atuar como a interface de desenvolvimento, enquanto o OCI Generative AI fornece o modelo de linguagem.