Tablestore:Compilação de conhecimento (Wiki)

O Wiki oferece páginas, links entre páginas, citações de origem e pesquisa semântica. Ele não armazena triplas de entidades nem expõe interfaces de consulta de grafo. Se você precisa de consultas de entidades ou relacionamentos no estilo de banco de dados de grafo, use um modelo de dados diferente.

Pré-requisitos

Criar um armazenamento de memória. Qualquer tipo de entrada é suportado para o armazenamento de memória.

Para usar os exemplos de SDK neste tópico, você precisa de:

• Uma chave de API para autenticação.

• Um endpoint de instância do Tablestore no formato https://<instance>.<region>.ots.aliyuncs.com.

• O nome da instância do Tablestore.

• O pacote SDK Python tablestore_agent_storage instalado.

O SDK atual do Agent Storage não fornece métodos de alto nível para o Wiki. Todos os exemplos de SDK neste tópico usam a chamada de baixo nível ots_client.request(Action, body).

No console, as operações do Wiki são organizadas nas seguintes páginas em Knowledge compilation Wiki:

• Raw files — Gerencie os arquivos de origem para compilação.

• Knowledge graph — Visualize páginas publicadas, metadados e links.

• Knowledge retrieval — Pesquise páginas publicadas.

Limites de recursos

Cada Wiki pertence a exatamente um armazenamento de memória e a um Agent Scope de três partes:

memoryStoreName + appId / tenantId / agentId

• O Wiki não usa runId; diferentes sessões do mesmo agente compartilham um Wiki.

• Todos os três campos de Scope são obrigatórios e podem conter até 128 bytes. Eles não devem conter / nem o curinga *.

Arquivos de origem suportados

Use Base64 padrão para arquivos binários. A extensão, o mediaType e a assinatura do arquivo devem corresponder.

Cotas e limites

Consultar um Wiki

Recupere ou crie o Wiki para o Agent Scope atual e visualize o status da compilação mais recente. A primeira chamada cria o Wiki automaticamente. Nenhum wikiId, ID de compilação ou ID de tarefa é necessário.

from tablestore_agent_storage import AgentStorageClient

client = AgentStorageClient(
    api_key="<your-api-key>",
    ots_endpoint="https://<instance>.<region>.ots.aliyuncs.com",
    ots_instance_name="<instance-name>",
)

wiki = client.ots_client.request("GetWiki", {
    "memoryStoreName": "agent_memory",
    "scope": {"appId": "app-001", "tenantId": "user-001", "agentId": "assistant"},
})
print(f"Status: {wiki.get('status')}, Page count: {wiki.get('pageCount')}, Pending build: {wiki.get('hasPendingChanges')}")

Compilar um Wiki

Compile de forma assíncrona os arquivos de origem em /.wiki/raw/ em um novo conjunto de páginas e publique-as atomicamente.

Antes de compilar, grave os arquivos de origem no diretório /.wiki/raw/. No console, use Add raw material ou Batch upload. No SDK, chame add_item com um caminho em /.wiki/raw/.

Após iniciar uma compilação, chame GetWiki para verificar o campo status. Quando o status atingir ready, as novas páginas estarão publicadas e disponíveis para leitura e pesquisa. Se o status for failed, verifique errorMessage, corrija as origens e inicie uma nova compilação. Se o status for conflict, recupere o status mais recente e inicie uma nova compilação.

Após uma compilação bem-sucedida, GetWiki.latestBuild.quality retorna métricas como cobertura de origem, status de citação de páginas e qualidade dos links. Uma compilação bem-sucedida não garante que todas as origens estejam totalmente representadas ou que todos os fatos sejam precisos. Verifique as páginas críticas manualmente. Para detalhes dos campos, consulte a referência da API GetWiki.

Status comuns de compilação:

from tablestore_agent_storage import AgentStorageClient

client = AgentStorageClient(
    api_key="<your-api-key>",
    ots_endpoint="https://<instance>.<region>.ots.aliyuncs.com",
    ots_instance_name="<instance-name>",
)

# 1. Write the source file (for AddItem, see the File memory document)
client.add_item({
    "memoryStoreName": "agent_memory",
    "scope": {"appId": "app-001", "tenantId": "user-001", "agentId": "assistant"},
    "path": "/.wiki/raw/product/payment.md",
    "content": "# Payment notes\n\nPayment callbacks must validate the idempotency key.",
})

# 2. Start the build
resp = client.ots_client.request("IngestWiki", {
    "memoryStoreName": "agent_memory",
    "scope": {"appId": "app-001", "tenantId": "user-001", "agentId": "assistant"},
    "clientToken": "wiki-build-001",
})
print(resp)

Listar páginas

Liste os metadados das páginas publicadas, incluindo caminhos, títulos e resumos, com suporte a paginação.

• As páginas ficam disponíveis somente após a compilação e publicação. Se nenhuma compilação tiver sido realizada, o serviço retorna um erro de recurso não encontrado.

• limit tem o valor padrão de 50 e o máximo de 100. Não analise nem modifique o nextToken; os resultados de paginação permanecem vinculados à mesma versão publicada.

from tablestore_agent_storage import AgentStorageClient

client = AgentStorageClient(
    api_key="<your-api-key>",
    ots_endpoint="https://<instance>.<region>.ots.aliyuncs.com",
    ots_instance_name="<instance-name>",
)

resp = client.ots_client.request("ListWikiPages", {
    "memoryStoreName": "agent_memory",
    "scope": {"appId": "app-001", "tenantId": "user-001", "agentId": "assistant"},
    "limit": 50,
})
for p in resp.get("pages", []):
    print(p.get("path"), p.get("title"))

Ler uma página

Leia o corpo completo de uma página publicada por caminho. Use ListWikiPages para obter os caminhos das páginas disponíveis.

from tablestore_agent_storage import AgentStorageClient

client = AgentStorageClient(
    api_key="<your-api-key>",
    ots_endpoint="https://<instance>.<region>.ots.aliyuncs.com",
    ots_instance_name="<instance-name>",
)

resp = client.ots_client.request("GetWikiPage", {
    "memoryStoreName": "agent_memory",
    "scope": {"appId": "app-001", "tenantId": "user-001", "agentId": "assistant"},
    "path": "/wiki/payment-callback.md",
})
print(resp.get("content"))

Pesquisar páginas

Use linguagem natural para pesquisar páginas publicadas de forma semântica. A pesquisa retorna o caminho, o título, o resumo e a pontuação das páginas correspondentes.

from tablestore_agent_storage import AgentStorageClient

client = AgentStorageClient(
    api_key="<your-api-key>",
    ots_endpoint="https://<instance>.<region>.ots.aliyuncs.com",
    ots_instance_name="<instance-name>",
)

resp = client.ots_client.request("SearchWikiPages", {
    "memoryStoreName": "agent_memory",
    "scope": {"appId": "app-001", "tenantId": "user-001", "agentId": "assistant"},
    "query": "How do payment callbacks ensure idempotency",
    "limit": 5,
})
for p in resp.get("pages", []):
    print(f"[{p.get('score')}] {p.get('path')} - {p.get('title')}")

Atualizar um Wiki

Atualize o nome ou o resumo de um Wiki.

from tablestore_agent_storage import AgentStorageClient

client = AgentStorageClient(
    api_key="<your-api-key>",
    ots_endpoint="https://<instance>.<region>.ots.aliyuncs.com",
    ots_instance_name="<instance-name>",
)

client.ots_client.request("UpdateWiki", {
    "memoryStoreName": "agent_memory",
    "scope": {"appId": "app-001", "tenantId": "user-001", "agentId": "assistant"},
    "name": "Payment and reconciliation Wiki",
    "summary": "Includes payment callbacks, reconciliation, and idempotency conventions",
})

Referências

• Criar um armazenamento de memória

• Memória de arquivos

• Memory Dream