Pular para o conteúdo principal

Criar, atualizar, e apagar KS via API

Os exemplos nesta seção usam curl e shell scripts. Você pode alterá-los. Use a StackSpot AI para adaptá-los para o idioma que desejar.

Pré-Requisitos

  • Devido às restrições de autenticação, o envio diretamente via API está disponível apenas para contas Enterprise.

  • Autentique-se para usar o script.

Siga os passos para autenticar na página de Credenciais de Serviço, para mais detalhes, acesse a documentação da StackSpot EDPn.

Cuidado!

Ative as seguintes permissões:

  • ai_dev and ai_admin.

Entre em contato com o administrador da sua conta se não conseguir criar uma Credencial de Serviço.

  • Copie os campos 'client id', 'client key', e 'realm' para usar como variáveis de ambiente (os dois primeiros devem ser segredos) ou no exemplo curl a parte inferior da página na seção 'como usar'. Você não poderá vê-los novamente.
Atenção!

Se você perder alguma delas, revogue a credencial e crie uma nova.

  • Os exemplos a seguir consideram que o token de acesso está definido como a variável de ambiente JWT. Você pode extrair isso da autenticação curl com o comando jq para obter o valor para a chave access_token do JSON retornado, depois salvá-lo como uma variável de ambiente usando o comando export, como:
export JWT=$(curl -s "https://idm.stackspot.com/$REALM/oidc/oauth/token" -H 'Content-Type: application/x-www-form-urlencoded' -d 'grant_type=client_credentials' -d "client_id=$CLIENT_ID" -d "client_secret=$CLIENT_KEY" | jq -r '.access_token')

Criar um Knowledge Source via API

Siga os passos:

Passo 1. Execute o comando para criar o KS:

curl -s -X POST "https://genai-code-buddy-api.stackspot.com/v1/knowledge-sources" -H "Authorization: Bearer $JWT" -H 'Content-Type: application/json' -d '{"slug": "<KS identifier in API>", "name": "<display name>", "description": "<more details about KS>", "type": "<one of API, SNIPPET or CUSTOM>"}'

Passo 2. Acesse o Portal da StackSpot AI.

  • Acesse a seção ‘Knowledge Sources’ no menu principal e procure pelo que você acabou de criar.

Fazer Upload de arquivos para um Knowledge Source existente

Atenção!

Ao adicionar novos arquivos a um Knowledge Source, o limite é de 10 MiB.

Cuidado!

Quando você faz upload de arquivos para um Knowledge Source, a extensão do arquivo no campo file_name é essencial. A StackSpot AI depende da extensão do arquivo para identificar a sintaxe do conteúdo, garantindo que o arquivo enviado seja processado e categorizado corretamente.

Por que a extensão do arquivo é importante

A extensão do arquivo permite que a StackSpot AI:

  1. Identifique automaticamente a sintaxe do conteúdo do arquivo;
  2. Aplique as regras de análise corretas para um processamento preciso;
  3. Torne o conteúdo fácil para pesquisar e utilizável dentro do Knowledge Source.

Exemplo

Se você fazer o upload de um arquivo chamado example.json, a StackSpot AI processará como um arquivo JSON. Se a extensão estiver ausente ou incorreta, o sistema pode não interpretar o conteúdo corretamente.

Você pode fazer o upload de um ou mais arquivos para uma Knowledge Source existente. Também é possível escolher fazer o upload de um arquivo zip. Siga os passos para realizar isso.

Cuidado!

Você precisa ter criado previamente um Knowledge Source aqui. Se ainda não criou, crie um agora.

Passo 1. Execute o seguinte script para iniciar o processo de upload:

upload_data=$(curl -X POST 'https://genai-code-buddy-api.stackspot.com/v1/file-upload/form' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $JWT" \
  -d '{"file_name": "<desired file's name with extension>", "target_id": "<KS slug>", "target_type": "KNOWLEDGE_SOURCE", "expiration": 600 }')

echo -n 'file upload id = '
echo "$upload_data" | jq -r '.id'

curl -X POST "$(echo "$upload_data" | jq -r '.url')" \
  -F "key=$(echo "$upload_data" | jq -r '.form.key')" \
  -F "x-amz-algorithm=$(echo "$upload_data" | jq -r '.form["x-amz-algorithm"]')" \
  -F "x-amz-credential=$(echo "$upload_data" | jq -r '.form["x-amz-credential"]')" \
  -F "x-amz-date=$(echo "$upload_data" | jq -r '.form["x-amz-date"]')" \
  -F "x-amz-security-token=$(echo "$upload_data" | jq -r '.form["x-amz-security-token"]')" \
  -F "policy=$(echo "$upload_data" | jq -r '.form.policy')" \
  -F "x-amz-signature=$(echo "$upload_data" | jq -r '.form["x-amz-signature"]')" \
  -F "file=@'<absolute path to desired file>'"

Passo 2. Para verificar o status do upload, execute o comando:

curl --location 'https://genai-code-buddy-api.stackspot.com/v1/file-upload/@<file upload id>' \
--header 'Authorization: Bearer $JWT'

Passo 3. Acesse o portal da StackSpot AI

Passo 4. No menu principal, clique em ‘Knowledge Sources’ e depois verifique se o seu Knowledge Source possui novos objetos.

Fazer upload de conteúdo standalone para um Knowledge Source existente

Atenção!

Você precisa ter criado previamente um Knowledge Source aqui. Se ainda não criou, crie um neste momento.

Apenas os tipos de KS mencionados suportam esse upload.

Snippet

curl -L 'https://genai-code-buddy-api.stackspot.com/v1/knowledge-sources/<KS slug>/snippets' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $JWT" \
  -d '{
      "use_case": "<description>",
      "code": "<content>",
      "language": "<one of sql, csp, freemarker2, systemverilog, sb, scheme, groovy, postiats, sol, mips, twig, php, aes, coffeescript, json, ocaml, sparql, xml, powershell, haskell, rust, scala, plaintext, octave, abap, lua, shell, less, r, yaml, fortran, bat, cobol, hcl, msdax, graphql, qsharp, objective-c, bicep, st, cpp, css, redis, javascript, julia, apex, dart, pug, markdown, flow9, sbcl, pascal, kotlin, c, csharp, pascaligo, scss, go, swift, proto, typescript, liquid, m3, razor, html, lexon, java, azcli, tcl, fsharp, ruby, vb, python, cameligo, ini, clojure, ada, elixir, restructuredtext, dockerfile, handlebars, racket, ecl, pla, perl, erlang, powerquery, verilog, d>" 
  }'

Personalizado

curl -L 'https://genai-code-buddy-api.stackspot.com/v1/knowledge-sources/<KS slug>/custom' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $JWT" \
  -d '{"content": "<content>"}'

Apagar Knowledge Sources Objects

Todos os Arquivos

Se você deseja apagar todos os Knowledge Source Objects, execute no seu terminal:

curl -s -X DELETE "https://genai-code-buddy-api.stackspot.com/v1/knowledge-sources/<KS slug>/objects" -H "Authorization: Bearer $JWT"

Standalone

Se você deseja excluir apenas o arquivo independente que você adicionou manualmente:

curl -s -X DELETE "https://genai-code-buddy-api.stackspot.com/v1/knowledge-sources/<KS slug>/objects?standalone=true" -H "Authorization: Bearer $JWT"

Apenas uploads

Para excluir os arquivos zip, execute o seguinte:

curl -s -X DELETE "https://genai-code-buddy-api.stackspot.com/v1/knowledge-sources/<KS slug>/objects?standalone=false" -H "Authorization: Bearer $JWT"