Criando uma API REST com Pinecone: Passo a Passo
Estamos construindo uma API REST com Pinecone que permite interagir com dados vetoriais sem esforço. Essa abordagem é crucial para quem busca implementar modelos de aprendizado de máquina e dados indexados sem se perder nos detalhes.
Pré-requisitos
- Python 3.11+
- pip install pinecone-io
- Conhecimento básico de APIs RESTful
Passo 1: Configurando Seu Ambiente
Primeiro, precisamos configurar o Python e instalar o cliente Pinecone. Certifique-se de ter a versão correta do Python. O cliente Python mais recente do Pinecone pode ser encontrado no GitHub:
pip install pinecone-clientInstale-o e verifique a instalação com o seguinte comando:
pip show pinecone-clientSe você receber um erro dizendo que o pacote não foi encontrado, provavelmente você está em um ambiente virtual que não possui a biblioteca correta ou a sua versão do Python é incompatível. Instale a versão correta ou ative o ambiente certo.
Passo 2: Inicializando o Pinecone
Para usar o Pinecone, precisamos inicializá-lo. Você precisará de uma chave de API que pode ser encontrada no seu painel do Pinecone. Veja como se conectar:
import pinecone
pinecone.init(api_key="YOUR_API_KEY", environment="us-west1-gcp")
Não se esqueça de substituir YOUR_API_KEY pela sua chave de API do Pinecone. Se essa linha gerar uma exceção, verifique se sua chave de API está correta ou se você configurou seu ambiente na região errada.
Passo 3: Criando um Índice
Agora precisamos criar um índice. Um índice é onde nossos vetores serão armazenados. Especifique o nome do índice e a dimensão dos vetores:
index_name = "example-index"
pinecone.create_index(index_name=index_name, dimension=128)Certifique-se de escolher uma dimensão que corresponda ao comprimento das suas incorporações de vetor. Se você tentar criar um índice com as dimensões erradas, verá um erro dizendo “Incompatibilidade de dimensão”.
Passo 4: Inserindo Dados no Índice
Depois que nosso índice estiver configurado, vamos inserir alguns dados. Para demonstração, estamos inserindo três vetores:
index = pinecone.Index(index_name)
# Dados de exemplo: (id, vetor)
data = [
("vec1", [0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1.0, 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1.0, 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1.0, 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8]),
("vec2", [0.2, 0.3, 0.1, 0.5, 0.6, 0.8, 0.9, 0.7, 0.1, 0.4, 0.2, 0.3, 0.5, 0.2, 0.1, 0.5, 0.3, 0.2, 0.1, 0.4, 0.6, 0.3, 0.5, 0.1, 0.8, 0.5, 0.4, 0.3, 0.2, 0.1, 0.5, 0.9, 0.6, 0.7, 0.3, 0.9, 0.5, 0.2],
("vec3", [0.3, 0.4, 0.1, 0.2, 0.5, 0.6, 0.1, 0.7, 0.8, 0.9, 0.4, 0.2, 0.6, 0.7, 0.8, 0.5, 0.3, 0.2, 0.3, 0.1, 0.9, 0.8, 0.5, 0.4, 0.7, 0.1, 0.3, 0.2, 0.4, 0.1, 0.5, 0.6, 0.9, 0.2, 0.3, 0.5, 0.8, 0.7)
]
index.upsert(items=data)Se você tentar inserir dados com vetores que não têm o comprimento correto, verá um erro reclamando sobre o tamanho do vetor. Sempre verifique suas dimensões.
Passo 5: Criando os Endpoints da API
Finalmente, precisamos de uma aplicação Flask para expor nossas operações do Pinecone como endpoints de API REST. Veja como configurar uma API simples:
from flask import Flask, request, jsonify
app = Flask(__name__)
@app.route('/vectors', methods=['POST'])
def add_vectors():
vectors = request.json.get('vectors')
index.upsert(items=vectors)
return jsonify({"status": "success", "message": "Vetores adicionados"}), 201
@app.route('/vectors/', methods=['GET'])
def get_vector(id):
vector = index.fetch(ids=[id])
return jsonify({"vector": vector}), 200
if __name__ == "__main__":
app.run(debug=True) Com essas rotas, você pode adicionar vetores através de uma requisição POST e recuperá-los com uma requisição GET. Não esqueça de incluir os cabeçalhos de tipo de conteúdo ao testar com ferramentas como o Postman. Se você esquecer disso, sua aplicação lançará um erro por falta de dados, então não pule essa parte.
As Armadilhas
- Exposição da Chave da API: É fácil acidentalmente enviar seu código para um repositório público com sua chave da API. Use variáveis de ambiente para armazenar dados sensíveis de forma segura.
- Limites de Índice do Pinecone: Diferentes níveis de assinaturas do Pinecone têm limites sobre o número de índices que você pode criar. Fique atento!
- Tratamento de Erros: Trate erros adequadamente em sua aplicação Flask. Se não fizer isso, sua interface pode quebrar sem indicar o que deu errado.
- Tamanho do Vetor: Sempre assegure que as dimensões dos seus vetores correspondam às dimensões do seu índice. Isso economizará horas de depuração.
Código Completo
import pinecone
from flask import Flask, request, jsonify
# Passo 1: Inicializar o Pinecone
pinecone.init(api_key="YOUR_API_KEY", environment="us-west1-gcp")
index_name = "example-index"
pinecone.create_index(index_name=index_name, dimension=128)
# Passo 2: Criar aplicação Flask
app = Flask(__name__)
index = pinecone.Index(index_name)
@app.route('/vectors', methods=['POST'])
def add_vectors():
vectors = request.json.get('vectors')
index.upsert(items=vectors)
return jsonify({"status": "success", "message": "Vetores adicionados"}), 201
@app.route('/vectors/', methods=['GET'])
def get_vector(id):
vector = index.fetch(ids=[id])
return jsonify({"vector": vector}), 200
if __name__ == "__main__":
app.run(debug=True) O Que Vem a Seguir
Agora que você tem uma API REST funcional, o próximo passo lógico é integrar um frontend para chamar essa API e visualizar os dados. Considere usar um aplicativo React simples ou qualquer framework moderno de frontend que permita fazer chamadas de API.
FAQ
- E se meus vetores não aparecerem no índice?
Certifique-se de que a solicitação de inserção está corretamente formatada e verifique os logs do servidor em busca de erros. - Posso armazenar diferentes dimensões de vetores?
Não, todos os vetores em um índice do Pinecone devem ter a mesma dimensão. - Como faço para excluir vetores?
Use o método delete do índice com o ID do vetor para remover entradas específicas.
Fontes de Dados
Confira a documentação oficial do Pinecone no GitHub para mais detalhes: pinecone-io/pinecone-python-client. Para especificidades da API, visite o fórum da Comunidade Pinecone.
| Repositório | Estrelas | Forks | Problemas Abertos | Licença | Última Atualização |
|---|---|---|---|---|---|
| pinecone-io/pinecone-python-client | 422 | 117 | 43 | Apache-2.0 | 2026-03-17 |
Última atualização em 26 de março de 2026. Dados coletados da documentação oficial e benchmarks da comunidade.
🕒 Published: