Tablestore:Gestion des documents

Python

Lors de l'utilisation de upload_documents, l'initialisation de AgentStorageClient nécessite les paramètres oss_endpoint et oss_bucket_name. À défaut, une erreur ValueError est levée.

from tablestore_agent_storage import AgentStorageClient

# To upload local files, configure OSS (the SDK first uploads files to OSS, then triggers chunking and vectorization)
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>",
)

resp = client.upload_documents({
    "knowledgeBaseName": "product_docs_kb",
    "documents": [
        {
            "filePath": "/home/user/docs/product_manual.pdf",
            "metadata": {"author": "John", "category": "Product documentation"}
        },
        {
            "filePath": "/home/user/docs/faq.docx",
            "metadata": {"author": "Jane", "category": "FAQ"}
        }
    ]
})

for detail in resp["data"]["documentDetails"]:
    print(detail["ossKey"], detail["status"])

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.add_documents({
    "knowledgeBaseName": "product_docs_kb",
    "documents": [
        {
            "ossKey": "oss://example-bucket/docs/product_manual.pdf",
            "metadata": {"author": "John"}
        }
    ]
})

resp = client.add_documents({
    "knowledgeBaseName": "product_docs_kb",
    "documents": [
        {
            "ossKey": "oss://example-bucket/docs/",
            "inclusionFilters": ["*.pdf", "*.docx"],
            "exclusionFilters": ["*draft*"]
        }
    ]
})

TypeScript

Pour télécharger des fichiers locaux en TypeScript, utilisez NodeAgentStorageClient et fournissez la configuration OSS.

import { NodeAgentStorageClient } from '@tablestore/agent-storage/node';

const client = new NodeAgentStorageClient({
  accessKeyId: '<AccessKey ID>',
  accessKeySecret: '<AccessKey Secret>',
  endpoint: 'https://<instance>.<region>.ots.aliyuncs.com',
  instanceName: '<instance-name>',
  ossEndpoint: 'https://oss-<region>.aliyuncs.com',
  ossBucketName: '<bucket-name>',
  ossAccessKeyId: '<AccessKey ID>',
  ossAccessKeySecret: '<AccessKey Secret>',
});

const resp = await client.uploadDocuments({
  knowledgeBaseName: 'product_docs_kb',
  documents: [
    {
      filePath: '/home/user/docs/product_manual.pdf',
      metadata: { author: 'John', category: 'Product documentation' },
    },
  ],
});

for (const detail of resp.data.documentDetails) {
  console.log(detail.ossKey, detail.status);
}

import { AgentStorageClient } from '@tablestore/agent-storage';

const client = new AgentStorageClient({
  apiKey: '<your-api-key>',
  endpoint: 'https://<instance>.<region>.ots.aliyuncs.com',
  instanceName: '<instance-name>',
});

const resp = await client.addDocuments({
  knowledgeBaseName: 'product_docs_kb',
  documents: [
    {
      ossKey: 'oss://example-bucket/docs/product_manual.pdf',
      metadata: { author: 'John' },
    },
  ],
});

const resp = await client.addDocuments({
  knowledgeBaseName: 'product_docs_kb',
  documents: [
    {
      ossKey: 'oss://example-bucket/docs/',
      inclusionFilters: ['*.pdf', '*.docx'],
      exclusionFilters: ['*draft*'],
    },
  ],
});

Python

import time

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>",
)

def wait_for_document(client, kb_name, doc_id, max_interval=30):
    """Poll document status with exponential backoff, waiting for indexing to complete."""
    interval = 3
    while True:
        resp = client.get_document({
            "knowledgeBaseName": kb_name,
            "docId": doc_id
        })
        status = resp["data"][0]["status"]
        if status == "Completed":
            print(f"Indexing complete, chunk count: {resp['data'][0].get('chunkNum', 'N/A')}")
            return resp
        elif status == "Failed":
            raise Exception(f"Indexing failed: {resp['data'][0].get('failedDetails')}")
        print(f"Current status: {status}, retrying in {interval}s...")
        time.sleep(interval)
        interval = min(interval * 2, max_interval)

wait_for_document(client, "product_docs_kb", "fc6ed97f-...")

La durée de traitement des documents dépend de la taille, du type et du nombre de fichiers. Les petits fichiers sont généralement traités en quelques secondes, tandis que les fichiers volumineux ou les importations par lot peuvent prendre plusieurs minutes.

TypeScript

import { AgentStorageClient } from '@tablestore/agent-storage';

const client = new AgentStorageClient({
  apiKey: '<your-api-key>',
  endpoint: 'https://<instance>.<region>.ots.aliyuncs.com',
  instanceName: '<instance-name>',
});

async function waitForDocument(kbName: string, docId: string, maxInterval = 30) {
  let interval = 3;
  while (true) {
    const resp = await client.getDocument({
      knowledgeBaseName: kbName,
      docId,
    });
    const doc = resp.data[0];
    if (doc.status === 'Completed') {
      console.log(`Indexing complete, chunk count: ${doc.chunkNum ?? 'N/A'}`);
      return resp;
    } else if (doc.status === 'Failed') {
      throw new Error(`Indexing failed: ${doc.failedDetails}`);
    }
    console.log(`Current status: ${doc.status}, retrying in ${interval}s...`);
    await new Promise((r) => setTimeout(r, interval * 1000));
    interval = Math.min(interval * 2, maxInterval);
  }
}

await waitForDocument('product_docs_kb', 'fc6ed97f-...');

Python

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.get_document({
    "knowledgeBaseName": "product_docs_kb",
    "docId": "fc6ed97f-..."
})

doc = resp["data"][0]
print(f"Status: {doc['status']}, chunk count: {doc.get('chunkNum', 'N/A')}")

TypeScript

import { AgentStorageClient } from '@tablestore/agent-storage';

const client = new AgentStorageClient({
  apiKey: '<your-api-key>',
  endpoint: 'https://<instance>.<region>.ots.aliyuncs.com',
  instanceName: '<instance-name>',
});

const resp = await client.getDocument({
  knowledgeBaseName: 'product_docs_kb',
  docId: 'fc6ed97f-...',
});

const doc = resp.data[0];
console.log(`Status: ${doc.status}, chunk count: ${doc.chunkNum ?? 'N/A'}`);

Python

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>",
)

# Get the first page
resp = client.list_documents({
    "knowledgeBaseName": "product_docs_kb",
    "maxResults": 20
})
for doc in resp["data"]["documentDetails"]:
    print(f"[{doc['status']}] {doc['ossKey']} (chunks: {doc.get('chunkNum', '-')})")

# Paginate
next_token = resp["data"].get("nextToken")
if next_token:
    resp = client.list_documents({
        "knowledgeBaseName": "product_docs_kb",
        "maxResults": 20,
        "nextToken": next_token
    })

TypeScript

import { AgentStorageClient } from '@tablestore/agent-storage';

const client = new AgentStorageClient({
  apiKey: '<your-api-key>',
  endpoint: 'https://<instance>.<region>.ots.aliyuncs.com',
  instanceName: '<instance-name>',
});

const resp = await client.listDocuments({
  knowledgeBaseName: 'product_docs_kb',
  maxResults: 20,
});
for (const doc of resp.data.documentDetails) {
  console.log(`[${doc.status}] ${doc.ossKey} (chunks: ${doc.chunkNum ?? '-'})`);
}

Python

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.update_document({
    "knowledgeBaseName": "product_docs_kb",
    "docId": "fc6ed97f-...",
    "metadata": {"author": "John", "category": "Technical documentation", "version": 2}
})

print(f"Update status: {resp['data']['updateStatus']}")  # UPDATED or NO_OP

TypeScript

import { AgentStorageClient } from '@tablestore/agent-storage';

const client = new AgentStorageClient({
  apiKey: '<your-api-key>',
  endpoint: 'https://<instance>.<region>.ots.aliyuncs.com',
  instanceName: '<instance-name>',
});

const resp = await client.updateDocument({
  knowledgeBaseName: 'product_docs_kb',
  docId: 'fc6ed97f-...',
  metadata: { author: 'John', category: 'Technical documentation', version: 2 },
});

console.log(`Update status: ${resp.data.updateStatus}`); // UPDATED or NO_OP

Python

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.delete_documents({
    "knowledgeBaseName": "product_docs_kb",
    "documents": [
        {"docId": "fc6ed97f-..."},
        {"ossKey": "oss://example-bucket/docs/faq.docx"}
    ]
})

# Check each deletion result
for detail in resp["data"]["documentDetails"]:
    print(f"{detail['ossKey']}: {detail['status']}")

TypeScript

import { AgentStorageClient } from '@tablestore/agent-storage';

const client = new AgentStorageClient({
  apiKey: '<your-api-key>',
  endpoint: 'https://<instance>.<region>.ots.aliyuncs.com',
  instanceName: '<instance-name>',
});

const resp = await client.deleteDocuments({
  knowledgeBaseName: 'product_docs_kb',
  documents: [
    { docId: 'fc6ed97f-...' },
    { ossKey: 'oss://example-bucket/docs/faq.docx' },
  ],
});

// Check each deletion result
for (const detail of resp.data.documentDetails) {
  console.log(`${detail.ossKey}: ${detail.status}`);
}