Pesquise documentos com lojas de vetores e chaves de API do OCI Generative AI

Crie um armazenamento de vetores, faça upload e ingira um documento e pesquise seu conteúdo com curl ou o OpenAI Python SDK usando uma chave de API do OCI Generative AI.

Visão Geral

Um armazenamento de vetores torna seus documentos pesquisáveis por significado. Você faz upload de um arquivo, o ingere no armazenamento e pesquisa com uma pergunta em linguagem natural. O serviço retorna passagens relevantes, nomes de arquivos e pontuações de relevância. As passagens recuperadas também podem fornecer contexto para um aplicativo de modelo de idioma.

Use armazenamentos de vetores para pesquisar políticas, guias de produtos e artigos de suporte sem criar seu próprio pipeline de análise e incorporação de documentos. Para obter uma introdução, consulte Lojas de Vetor e Lojas Semânticas.

Neste tutorial, você:

  • Criar, recuperar e listar armazenamentos de vetores.
  • Faça upload de um documento de amostra e o ingira em partes pesquisáveis.
  • Pesquise o documento e inspecione as passagens correspondentes.
  • Renomeie a loja e exclua os recursos de teste.

Cada tarefa numerada fornece um exemplo curl e um exemplo Python (OpenAI SDK). Escolha um caminho e siga-o do início ao fim. Os exemplos de curl fazem solicitações HTTP do Bash. Os exemplos de Python usam o SDK OpenAI configurado para chamar o OCI. Ambos os caminhos são autenticados com uma chave de API do OCI Generative AI e não exigem uma sessão da CLI do OCI.

Antes de Começar

Para concluir este tutorial, você precisa:

Os exemplos usam este URL base do OCI:

https://inference.generativeai.us-chicago-1.oci.oraclecloud.com/20231130/openai/v1

Use o ponto final de serviço para a região selecionada. Mantenha o mesmo ponto final, compartimento e projeto durante todo o tutorial.

O documento de amostra contém uma política de loja fictícia. Substitua apenas os placeholders de conexão por seus próprios valores. Os exemplos solicitam a chave da API sem exibi-la ou incluí-la no código-fonte.

Configurar o caminho do curl

Em um terminal Bash, substitua os placeholders do compartimento e do projeto e execute:

set -o pipefail
export GENAI_BASE_URL='https://inference.generativeai.us-chicago-1.oci.oraclecloud.com/20231130/openai/v1'
export GENAI_COMPARTMENT_ID='<your-compartment-ocid>'
export GENAI_PROJECT_ID='<your-project-ocid>'

read -r -s -p 'OCI Generative AI API key: ' GENAI_API_KEY
printf '\n'
export GENAI_API_KEY

VECTOR_STORES_URL="$GENAI_BASE_URL/vector_stores"
FILES_URL="$GENAI_BASE_URL/files"

Execute cada exemplo de curl neste terminal para que as configurações e os IDs de recursos retornados permaneçam disponíveis. As solicitações enviam a chave de API do portador e opc-compartment-id. Os uploads e a exclusão de arquivos também enviam OpenAI-Project para identificar seu projeto do OCI. Defina o URL base sem uma barra à direita.

Se um comando falhar, resolva o erro antes de continuar. Mantenha os IDs retornados por solicitações de limpeza bem-sucedidas. Não execute novamente um comando de criação ou upload bem-sucedido apenas para recuperar o status de um recurso.

Configurar o Caminho do Python

Crie e ative um ambiente virtual e instale o OpenAI Python SDK:

python3 -m venv .venv
. .venv/bin/activate
python -m pip install --upgrade openai

Crie vector_store_tutorial.py com a configuração a seguir. Substitua os placeholders do compartimento e do projeto. Em seguida, anexe o bloco Python de cada uma das oito tarefas numeradas em ordem. Todos os blocos compartilham as mesmas variáveis de cliente e recurso.

import getpass
import time

from openai import OpenAI

BASE_URL = "https://inference.generativeai.us-chicago-1.oci.oraclecloud.com/20231130/openai/v1"
COMPARTMENT_ID = "<your-compartment-ocid>"
PROJECT_ID = "<your-project-ocid>"
API_KEY = getpass.getpass("OCI Generative AI API key: ")

client = OpenAI(
    api_key=API_KEY,
    base_url=BASE_URL.rstrip("/") + "/",
    default_headers={"opc-compartment-id": COMPARTMENT_ID},
    timeout=30,
)

Depois de salvar o documento de amostra e montar todos os blocos Python, execute o script concluído no mesmo diretório:

python vector_store_tutorial.py

O script concluído cria recursos, pesquisa o documento e exclui seu armazenamento e arquivo carregado. Para tentar mais perguntas antes da limpeza, adicione chamadas de pesquisa após a tarefa 6 e antes do bloco de exclusão. Se o script parar em caso de erro, use os IDs de recursos impressos antes do erro para inspecionar e limpar os recursos já criados.

Preparar um documento de amostra

Salve esta política fictícia como sample-document.txt no diretório em que você executa os comandos curl ou o script Python:

Example shop policy

Returns
Customers can return unused purchases within 30 days of delivery.
Include the order number and keep the item in its original packaging.
Contact support before shipping a return.
Refunds go to the original payment method.

Delivery
Standard delivery usually takes 3 to 5 business days.
Express delivery usually takes 1 to 2 business days.

1. Criar um Vector Store

Crie um armazenamento vazio com um nome reconhecível. O exemplo define uma política de expiração de um dia com base no last_active_at. A criação do armazenamento não faz upload nem ingere um documento.

Execute o exemplo para o caminho escolhido.

curl

STORE_RESPONSE=$(curl --fail-with-body --silent --show-error \
  --request POST "$VECTOR_STORES_URL" \
  --header "Authorization: Bearer $GENAI_API_KEY" \
  --header "opc-compartment-id: $GENAI_COMPARTMENT_ID" \
  --header 'Content-Type: application/json' \
  --data '{"name":"document-search-demo","expires_after":{"anchor":"last_active_at","days":1}}')

printf '%s\n' "$STORE_RESPONSE" | jq '{id, name, status}'
VECTOR_STORE_ID=$(printf '%s' "$STORE_RESPONSE" | jq -er '.id')

Python (OpenAI SDK)

store = client.vector_stores.create(
    name="document-search-demo",
    expires_after={"anchor": "last_active_at", "days": 1},
)
print("Created store:", store.id, store.status)

Salve o ID da loja retornada. A criação pode ser assíncrona. Verifique seu status na próxima tarefa.

2. Recuperar a Loja e Verificar Seu Status

Recupere os metadados do armazenamento e aguarde o completed antes de ingerir um documento.

Execute o exemplo para o caminho escolhido.

curl

curl --fail-with-body --silent --show-error \
  "$VECTOR_STORES_URL/$VECTOR_STORE_ID" \
  --header "Authorization: Bearer $GENAI_API_KEY" \
  --header "opc-compartment-id: $GENAI_COMPARTMENT_ID" \
  | jq '{id, name, status}'

Se o status for in_progress, aguarde dois segundos e execute o comando de recuperação novamente. Continue somente quando o status for completed. Interrompa e investigue se a loja expira ou permanece em andamento por mais de dois minutos.

Python (OpenAI SDK)

store = client.vector_stores.retrieve(store.id)
deadline = time.monotonic() + 120
while store.status == "in_progress":
    if time.monotonic() >= deadline:
        raise TimeoutError(f"Store creation is still in progress: {store.id}")
    time.sleep(2)
    store = client.vector_stores.retrieve(store.id)

if store.status != "completed":
    raise RuntimeError(f"Store is not ready: {store.id}, {store.status}")
print("Store is ready:", store.id)

O tempo limite de sondagem de dois minutos é um limite para este exemplo, não uma garantia de conclusão do serviço. Se ele for atingido, mantenha o ID da loja e inspecione a loja antes de tentar novamente.

A loja está pronta para ingestão.

3. Listar Lojas de Vetor

Listar lojas para localizar recursos que você já criou. Este exemplo exibe a primeira página com até dez entradas. Uma loja pode estar em uma página posterior. Recuperar por ID para verificar uma loja específica.

Execute o exemplo para o caminho escolhido.

curl

curl --fail-with-body --silent --show-error \
  "$VECTOR_STORES_URL?limit=10" \
  --header "Authorization: Bearer $GENAI_API_KEY" \
  --header "opc-compartment-id: $GENAI_COMPARTMENT_ID" \
  | jq '.data[] | {id, name, status}'

Python (OpenAI SDK)

for item in client.vector_stores.list(limit=10).data:
    print(item.id, item.name, item.status)

A saída mostra o ID, o nome e o status de cada loja retornada.

4. Fazer Upload de Documento

Faça upload do documento de amostra para criar um recurso de arquivo. O cabeçalho OpenAI-Project associa o upload ao seu projeto do OCI Generative AI. O arquivo se torna pesquisável após a ingestão na próxima tarefa.

Execute o exemplo para o caminho escolhido.

curl

FILE_RESPONSE=$(curl --fail-with-body --silent --show-error \
  --request POST "$FILES_URL" \
  --header "Authorization: Bearer $GENAI_API_KEY" \
  --header "opc-compartment-id: $GENAI_COMPARTMENT_ID" \
  --header "OpenAI-Project: $GENAI_PROJECT_ID" \
  --form 'purpose=assistants' \
  --form 'file=@sample-document.txt')

printf '%s\n' "$FILE_RESPONSE" | jq '{id, filename}'
FILE_ID=$(printf '%s' "$FILE_RESPONSE" | jq -er '.id')

Python (OpenAI SDK)

with open("sample-document.txt", "rb") as document:
    uploaded_file = client.files.create(
        file=document,
        purpose="assistants",
        extra_headers={"OpenAI-Project": PROJECT_ID},
    )
print("Uploaded file:", uploaded_file.id, uploaded_file.filename)

Para curl, deixe o comando definir o tipo de conteúdo multiparte e o limite automaticamente.

Salve o ID do arquivo retornado para ingestão e limpeza.

5. Ingerir o Documento na Loja

A ingestão associa o arquivo ao armazenamento, divide o documento em partes e cria incorporações para recuperação. Um lote de arquivos pode conter vários arquivos. Este exemplo usa um arquivo e as configurações de divisão em blocos padrão.

Execute o exemplo para o caminho escolhido.

curl

BATCH_RESPONSE=$(curl --fail-with-body --silent --show-error \
  --request POST "$VECTOR_STORES_URL/$VECTOR_STORE_ID/file_batches" \
  --header "Authorization: Bearer $GENAI_API_KEY" \
  --header "opc-compartment-id: $GENAI_COMPARTMENT_ID" \
  --header 'Content-Type: application/json' \
  --data "$(jq -n --arg file_id "$FILE_ID" '{file_ids:[$file_id]}')")

printf '%s\n' "$BATCH_RESPONSE" | jq '{id, status, file_counts}'
BATCH_ID=$(printf '%s' "$BATCH_RESPONSE" | jq -er '.id')

Verifique o status do lote:

curl --fail-with-body --silent --show-error \
  "$VECTOR_STORES_URL/$VECTOR_STORE_ID/file_batches/$BATCH_ID" \
  --header "Authorization: Bearer $GENAI_API_KEY" \
  --header "opc-compartment-id: $GENAI_COMPARTMENT_ID" \
  | jq '{id, status, file_counts}'

Se o status for in_progress, aguarde dois segundos e recupere o batch novamente. Continue quando o status for completed, a contagem de arquivos concluída for uma e as contagens com falha e canceladas forem zero. Interrompa e investigue se a ingestão falhar, for cancelada ou permanecer em andamento por mais de dois minutos.

Python (OpenAI SDK)

batch = client.vector_stores.file_batches.create(
    vector_store_id=store.id,
    file_ids=[uploaded_file.id],
)
print("Ingestion batch:", batch.id)

deadline = time.monotonic() + 120
while batch.status == "in_progress":
    if time.monotonic() >= deadline:
        raise TimeoutError(f"Document ingestion is still in progress: {batch.id}")
    time.sleep(2)
    batch = client.vector_stores.file_batches.retrieve(
        batch.id, vector_store_id=store.id,
    )

counts = batch.file_counts
if (
    batch.status != "completed"
    or counts.completed != 1
    or counts.failed
    or counts.cancelled
):
    raise RuntimeError(
        f"Ingestion did not succeed: {batch.id}, {batch.status}, {counts}"
    )
print("Document is ready to search.")

O documento está pronto para pesquisa após a ingestão bem-sucedida. Consulte API de Lotes de Arquivos de Armazenamento de Vetor para obter mais informações.

6. Pesquisar o Documento

Faça uma pergunta em linguagem natural para recuperar passagens relevantes. A chamada de pesquisa retorna o conteúdo do documento. Não gera uma resposta de modelo de linguagem.

Execute o exemplo para o caminho escolhido.

curl

Python (OpenAI SDK)

Procure uma passagem que contenha o período de devolução de 30 dias da política de amostra. Limites de passagem, ordenação e pontuações podem variar. O max_num_results limita os chunks correspondentes, não os documentos.

Tente outra pergunta, como Quão rápido é a entrega expressa? ou O que devo incluir em uma devolução? Repita apenas a chamada de pesquisa enquanto a loja e o arquivo ainda existirem.

7. Renomear o Armazenamento

Atualize o nome da loja. A renomeação altera os metadados do armazenamento e deixa o texto da política submetido a upload inalterado.

Execute o exemplo para o caminho escolhido.

curl

curl --fail-with-body --silent --show-error \
  --request POST "$VECTOR_STORES_URL/$VECTOR_STORE_ID" \
  --header "Authorization: Bearer $GENAI_API_KEY" \
  --header "opc-compartment-id: $GENAI_COMPARTMENT_ID" \
  --header 'Content-Type: application/json' \
  --data '{"name":"document-search-demo-updated"}' \
  | jq '{id, name, status}'

Se o status for in_progress, use o comando recuperar da tarefa 2 até que o status seja completed. Interrompa e investigue se a atualização não for concluída dentro do período de sondagem de dois minutos do exemplo.

Python (OpenAI SDK)

store = client.vector_stores.update(
    store.id, name="document-search-demo-updated",
)
deadline = time.monotonic() + 120
while store.status == "in_progress":
    if time.monotonic() >= deadline:
        raise TimeoutError(f"Store update is still in progress: {store.id}")
    time.sleep(2)
    store = client.vector_stores.retrieve(store.id)

if store.status != "completed":
    raise RuntimeError(f"Store update did not complete: {store.id}, {store.status}")
print("Updated store:", store.id, store.name)

A loja tem o nome atualizado. Aguarde a conclusão da atualização antes de excluí-la.

8, Excluir os Recursos de Teste

Exclua o armazenamento e o arquivo carregado criado neste tutorial. São recursos separados. Excluir o armazenamento não substitui excluir o arquivo. Utilize apenas os IDs dos recursos de teste criados.

Se uma tarefa anterior falhar, use os IDs impressos pelas tarefas bem-sucedidas para limpar apenas os recursos existentes. Mantenha as mesmas definições de ponto final, compartimento, projeto e chave de API. Para Python, execute o bloco de configuração com o bloco de exclusão e substitua store.id e uploaded_file.id pelos IDs salvos como strings entre aspas. Omita a exclusão de qualquer recurso que não foi criado.

Execute o exemplo para o caminho escolhido.

curl

curl --fail-with-body --silent --show-error \
  --request DELETE "$VECTOR_STORES_URL/$VECTOR_STORE_ID" \
  --header "Authorization: Bearer $GENAI_API_KEY" \
  --header "opc-compartment-id: $GENAI_COMPARTMENT_ID" \
  | jq '{id, deleted}'

curl --fail-with-body --silent --show-error \
  --request DELETE "$FILES_URL/$FILE_ID" \
  --header "Authorization: Bearer $GENAI_API_KEY" \
  --header "opc-compartment-id: $GENAI_COMPARTMENT_ID" \
  --header "OpenAI-Project: $GENAI_PROJECT_ID" \
  | jq '{id, deleted}'

Python (OpenAI SDK)

deleted_store = client.vector_stores.delete(store.id)
print("Store deleted:", deleted_store.id, deleted_store.deleted)

deleted_file = client.files.delete(
    uploaded_file.id,
    extra_headers={"OpenAI-Project": PROJECT_ID},
)
print("File deleted:", deleted_file.id, deleted_file.deleted)
client.close()

Uma confirmação de exclusão bem-sucedida contém deleted: true. Confirme este valor para ambos os recursos.

Diagnóstico e Solução de Problemas

SintomaO que verificar
Erro de autenticação ou HTTP 401Confirme se o segredo da chave da API do OCI Generative AI é válido para a região selecionada e é enviado como um token de portador.
Erro de autorização ou HTTP 403Verifique as permissões de chave de API e as permissões de Armazenamento de Arquivos e Vetores para o compartimento e o projeto.
Recurso não encontradoVerifique o URL de serviço, a região, o compartimento, o cabeçalho do projeto para obter solicitações de arquivo e o ID do recurso.
Upload rejeitadoVerifique o tipo de arquivo e os limites de upload no tópico API de Arquivos. Comece com o pequeno documento de amostra.
Falha na ingestãoRecupere o lote e inspecione seu status e contagens de arquivos. Recupere registros de arquivo de armazenamento de vetores individuais para obter detalhes do erro.
Não há resultados da pesquisaConfirme se a ingestão foi concluída com sucesso e se você está pesquisando a loja que contém o documento.
Timeout de sondagemRecupere o recurso novamente para inspecionar seu status atual. Guarde seu ID para solução de problemas e limpeza.
O SDK não tem o método vector_stores ou searchAtive o ambiente Python usado pelo script e atualize o pacote openai.