Busca em arquivos

RAG integrado: upload de arquivos, vector stores e respostas baseadas nos seus documentos.

Atualizado em 10 de ago. de 2026

A busca em arquivos dá ao assistente conhecimento que não está no modelo — manuais, políticas, relatórios, qualquer documento seu. Você sobe os arquivos para vector stores; a plataforma extrai o texto, fatia, gera os embeddings e indexa. Na execução, o modelo decide quando buscar, e a resposta vem fundamentada nos trechos encontrados.

Quickstart

1
Crie o assistente com file_search
Adicione {"type": "file_search"} em tools — os documentos podem vir depois.
2
Suba os arquivos
Um POST /v1/files multipart com purpose=assistants para cada documento.
3
Crie a vector store e adicione os arquivos
Um POST /v1/vector_stores, depois POST /v1/vector_stores/{id}/files com cada file_id. A ingestão é assíncrona — aguarde o status completed.
4
Vincule ao assistente
Atualize tool_resources.file_search.vector_store_ids com o id da store.
5
Rode
Pergunte algo que está nos documentos. O run mostra a busca nos steps e a resposta cita o conteúdo.

# 1. assistente
ASST=$(curl -s https://api.hinow.ai/v1/assistants \
  -H "Authorization: Bearer hi_SUA_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "model": "hinow/himax",
    "name": "RH",
    "instructions": "Responda com base nos documentos internos.",
    "tools": [{"type": "file_search"}]
  }' | jq -r .id)

# 2. arquivo
FILE=$(curl -s https://api.hinow.ai/v1/files \
  -H "Authorization: Bearer hi_SUA_API_KEY" \
  -F "file=@politica_ferias.pdf" -F "purpose=assistants" | jq -r .id)

# 3. vector store + arquivo
VS=$(curl -s https://api.hinow.ai/v1/vector_stores \
  -H "Authorization: Bearer hi_SUA_API_KEY" -H "Content-Type: application/json" \
  -d '{"name": "Docs RH"}' | jq -r .id)
curl -s https://api.hinow.ai/v1/vector_stores/$VS/files \
  -H "Authorization: Bearer hi_SUA_API_KEY" -H "Content-Type: application/json" \
  -d "{\"file_id\": \"$FILE\"}"
# aguarde: GET /v1/vector_stores/$VS/files/$FILE até status=completed

# 4. vincular
curl -s https://api.hinow.ai/v1/assistants/$ASST \
  -H "Authorization: Bearer hi_SUA_API_KEY" -H "Content-Type: application/json" \
  -d "{\"tool_resources\": {\"file_search\": {\"vector_store_ids\": [\"$VS\"]}}}"

# 5. perguntar
curl -s https://api.hinow.ai/v1/threads/runs \
  -H "Authorization: Bearer hi_SUA_API_KEY" -H "Content-Type: application/json" \
  -d "{\"assistant_id\": \"$ASST\", \"thread\": {\"messages\": [\
       {\"role\": \"user\", \"content\": \"Quantos dias de férias posso vender?\"}]}}"

Como funciona

Na execução, o file_search vira uma ferramenta que o modelo chama com a consulta que ele mesmo formula. A busca é semântica, roda sobre os vector stores do assistente e da thread, e devolve os trechos mais relevantes (até 8 por busca) para o modelo compor a resposta.

O que foi encontrado fica registrado nos run steps — cada busca aparece como um step tool_calls com file_id, file_name e score de cada resultado:

{
  "type": "tool_calls",
  "tool_calls": [{
    "type": "file_search",
    "file_search": {
      "results": [
        {"file_id": "file-8bcac8...", "file_name": "politica_ferias.pdf", "score": 0.59}
      ]
    }
  }]
}

Arquivos

POSThttps://api.hinow.ai/v1/filesBearer

Sobe um arquivo (multipart/form-data).

Parâmetros

filefile· bodyobrigatório
Até 25 MB. PDF, TXT, Markdown, DOCX e demais formatos de texto.
purposestring· bodyobrigatório
assistants para busca em arquivos.

Respostas

200O objeto file — guarde o id

O restante do CRUD: GET /v1/files (aceita ?purpose=), GET /v1/files/{id}, GET /v1/files/{id}/content (o binário) e DELETE /v1/files/{id}.

Vector stores

CRUD completo em /v1/vector_stores (criar, listar, ler, editar, remover) e arquivos da store em /v1/vector_stores/{id}/files. O objeto traz file_counts com o progresso da ingestão:

{"total": 2, "completed": 2, "in_progress": 0, "failed": 0, "cancelled": 0}

Para volumes maiores, os file batches adicionam vários arquivos numa chamada e dão o progresso agregado — é o que os helpers upload_and_poll dos SDKs usam:

# vários arquivos de uma vez
curl -s https://api.hinow.ai/v1/vector_stores/$VS/file_batches \
  -H "Authorization: Bearer hi_SUA_API_KEY" -H "Content-Type: application/json" \
  -d '{"file_ids": ["file-aaa", "file-bbb", "file-ccc"]}'

# progresso
curl -s https://api.hinow.ai/v1/vector_stores/$VS/file_batches/$BATCH \
  -H "Authorization: Bearer hi_SUA_API_KEY"

Threads também têm documentos

Uma thread pode carregar tool_resources.file_search.vector_store_ids próprios — útil para juntar os documentos permanentes do assistente com um arquivo específico daquela conversa. A busca cobre os dois.

Esta página foi útil?