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:
- Uma chave de API do OCI Generative AI autorizada para a região e o compartimento selecionados. Use um dos valores de segredo da chave quando solicitado.
- Permissão para gerenciar arquivos e armazenamentos de vetores nesse compartimento. Consulte Permissões de Arquivo, Permissões de Armazenamento de Vetor e Adicionando Permissões de Chave de API.
- Um projeto do OCI Generative AI existente para uploads de arquivos. Copie seu OCID e o OCID de seu compartimento. Se necessário, crie um projeto antes de iniciar.
- Acesso a uma região em que as APIs de Armazenamento de Arquivos e Vetores estão disponíveis. Os exemplos usam o Centro-Oeste dos EUA (Chicago),
us-chicago-1. Consulte Regiões para Enterprise AI Agents e os tópicos API de Arquivos e API de Lotes de Arquivos do Vector Store. - Para curl, Bash, curl com suporte a
--fail-with-bodyejq. Para Python, Python 3.11 ou posterior e o pacoteopenai.
Os exemplos usam este URL base do OCI:
https://inference.generativeai.us-chicago-1.oci.oraclecloud.com/20231130/openai/v1Use 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 openaiCrie 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.pyO 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.
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.
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.
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.
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.
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.
curl
curl --fail-with-body --silent --show-error \
--request POST "$VECTOR_STORES_URL/$VECTOR_STORE_ID/search" \
--header "Authorization: Bearer $GENAI_API_KEY" \
--header "opc-compartment-id: $GENAI_COMPARTMENT_ID" \
--header 'Content-Type: application/json' \
--data '{"query":"How long do I have to return a purchase?","max_num_results":3}' \
| jq '.data[] | {filename, score, text:[.content[] | select(.type == "text") | .text]}'Python (OpenAI SDK)
query = "How long do I have to return a purchase?"
results = client.vector_stores.search(
vector_store_id=store.id,
query=query,
max_num_results=3,
)
print("Question:", query)
if not results.data:
print("No matching passages found.")
for result in results.data:
print(f"\n{result.filename} (score: {result.score:.3f})")
for content in result.content:
if content.type == "text":
print(content.text)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.
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.
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
| Sintoma | O que verificar |
|---|---|
| Erro de autenticação ou HTTP 401 | Confirme 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 403 | Verifique 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 encontrado | Verifique 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 rejeitado | Verifique 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ão | Recupere 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 pesquisa | Confirme se a ingestão foi concluída com sucesso e se você está pesquisando a loja que contém o documento. |
| Timeout de sondagem | Recupere 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 search | Ative o ambiente Python usado pelo script e atualize o pacote openai. |