Tablestore:Crie sua primeira base de conhecimento

Pré-requisitos

• Você já criou uma instância do AgentStorage e obteve seu nome e endpoint. A base de conhecimento será criada nesta instância.

• Você já criou um bucket do Object Storage Service (OSS) na mesma região da instância do AgentStorage e autorizou o Tablestore a ler e gravar no OSS.

• Você possui um AccessKey ID e um AccessKey secret. Em ambientes de produção, utilize um usuário RAM ou credenciais temporárias.

• Você dispõe de um arquivo local em formato PDF, Word, Markdown ou texto para testes.

Etapa 1: Instale o SDK

Execute o comando a seguir para instalar o AgentStorage Python SDK:

pip install tablestore-agent-storage

Etapa 2: Crie um cliente

Crie um AgentStorageClient com o par de AccessKey e as informações da instância e do bucket obtidas nos pré-requisitos. Os trechos de código Python das etapas 2 a 5 formam um único script. Adicione-os ao mesmo arquivo ou execute-os na mesma sessão para que variáveis compartilhadas, como client e doc_id, permaneçam definidas.

from tablestore_agent_storage import AgentStorageClient
import time

client = AgentStorageClient(
    access_key_id="<AccessKey ID>",
    access_key_secret="<AccessKey Secret>",
    ots_endpoint="https://<instance>.<region>.ots.aliyuncs.com",
    ots_instance_name="<instance-name>",
    oss_endpoint="https://oss-<region>.aliyuncs.com",
    oss_bucket_name="<bucket-name>",
)

Substitua os placeholders pelos seus valores reais. O subdomínio <instance> em ots_endpoint e o valor <instance-name> de ots_instance_name referem-se ao mesmo nome de instância. Os dois placeholders <region> recebem o mesmo valor porque o bucket do OSS está na mesma região da instância.

Etapa 3: Crie uma base de conhecimento e envie um documento

Esta etapa realiza duas chamadas: create_knowledge_base cria a base de conhecimento e upload_documents importa seu documento local para ela.

Primeiro, crie uma base de conhecimento chamada product_docs_kb:

client.create_knowledge_base({
    "knowledgeBaseName": "product_docs_kb",
    "description": "Product documentation knowledge base",
})

Em seguida, envie um documento local e salve o ID do documento que a Etapa 4 usará para acompanhar o progresso da indexação:

response = client.upload_documents({
    "knowledgeBaseName": "product_docs_kb",
    "documents": [{"filePath": "/path/to/product-guide.pdf"}],
})
doc_id = response["data"]["documentDetails"][0]["docId"]

O SDK primeiro envia o arquivo local para o OSS e depois submete uma tarefa de importação assíncrona. Como nenhuma configuração de recuperação foi especificada durante a criação da base de conhecimento, o service utiliza suas configurações padrão.

Etapa 4: Aguarde até que o documento esteja pesquisável

A tarefa de importação é executada de forma assíncrona. Um documento não pode ser recuperado enquanto seu status for pending ou indexing. Consulte o status do documento a cada 5 segundos com o código a seguir. Não prossiga para a próxima etapa até que o status mude para completed:

deadline = time.time() + 300

while time.time() < deadline:
    response = client.get_document({
        "knowledgeBaseName": "product_docs_kb",
        "docId": doc_id,
    })
    document = response["data"][0]
    status = document["status"]

    if status == "completed":
        break
    if status == "failed":
        raise RuntimeError(document.get("message", "Document processing failed"))
    time.sleep(5)
else:
    raise TimeoutError("Timed out waiting for document indexing")

Etapa 5: Realize a recuperação

Depois que o documento se tornar pesquisável, consulte a base de conhecimento para obter conteúdo relevante a uma pergunta em texto:

response = client.retrieve({
    "knowledgeBaseName": "product_docs_kb",
    "retrievalQuery": {
        "type": "TEXT",
        "text": "What are the installation steps for the product?",
    },
})

for item in response["data"]["retrievalResults"]:
    print(f"[{item['score']:.4f}] {item['content'][:120]}")

Em caso de sucesso, o script imprime uma linha para cada fragmento recuperado: uma pontuação de relevância entre colchetes, seguida pelos primeiros 120 caracteres do conteúdo do fragmento. Se o status do documento for completed e a consulta de recuperação retornar fragmentos pontuados do seu documento, a base de conhecimento estará indexada e pronta para pesquisa. Essas etapas completam todo o fluxo de trabalho do AgentStorage, desde o documento bruto até a indexação de fragmentos e a recuperação de conteúdo relevante. Os resultados recuperados são fragmentos de evidência para aplicações de geração aumentada por recuperação (RAG), e não respostas finais geradas por um modelo.

Próximas etapas

• Saiba mais sobre o Knowledge Storage Service: Knowledge Storage Service.

• Importe arquivos ou diretórios do OSS: Document management.

• Ajuste a recuperação híbrida e o reranking: Retrieval and Ranking.

• Utilize TypeScript, a interface de linha de comando (CLI) ou o Dashboard: Agent Storage SDK, Command-line tool.