すべてのプロダクト
Search
ドキュメントセンター

Tablestore:ドキュメント管理

最終更新日:Oct 22, 2026

AgentStorage ナレッジベース内のドキュメントを管理します。これには、インポート、クエリ、一覧表示、更新、削除の操作が含まれます。ローカルコンピューターまたは Object Storage Service (OSS) からファイルをインポートし、アップロードから検索まで各ドキュメントを追跡できます。

前提条件

  • AgentStorage インスタンス、およびそのアクセスエンドポイントとインスタンス名。 詳細については、「AgentStorage インスタンスを作成する」をご参照ください。

  • ナレッジベース。詳細については、「ナレッジベースの管理」をご参照ください。

  • AgentStorage SDK がインストールされ、認証済みであること。手順については、「Agent Storage SDK」をご参照ください。

  • ローカルコンピューターからドキュメントをアップロードするには、インスタンスと同じリージョンにある OSS バケットと、完了した OSS 認証が必要です。SDK を初期化する際に、アクセスキーペア、OSS エンドポイント、バケット名などの OSS 設定も指定します。

  • (条件付き) 画像を保存し、マルチモーダル検索を使用するには、ナレッジベースでマルチモーダルが有効になっている必要があります。マルチモーダルはナレッジベースの作成時にのみ有効にでき、一度有効にするとこの設定は変更できません。

  • (条件付き) ナレッジベースでサブスペースが有効になっている場合は、すべてのインポートおよび一覧表示リクエストで subspace パラメーターを指定する必要があります。

  • (条件付き) アップロード中にドキュメントのメタデータを入力するには、ナレッジベースにメタデータスキーマが設定されている必要があります。

サポートされているドキュメント形式

AgentStorage ナレッジベースは、次のファイル形式をサポートしています。

タイプファイル名拡張子
PDF.pdf
Word.doc、.docx
Excel.xls、.xlsx
PowerPoint.ppt、.pptx
プレーンテキスト.txt
Markdown.md
構造化テキスト.csv、.xml、.html、.json
画像.jpeg、.png、.bmp、.webp、.gif、.tiff

ドキュメントのインポートには、次の制限があります。

  • リクエストあたりのドキュメント数:各リクエストは最大 10 個のドキュメントをサポートします。

  • ファイルサイズ:各ファイルは最大 50 MB です。

  • 上限の引き上げ:より高い上限をリクエストするには、チケットを起票するか、Tablestore テクニカルサポートの DingTalk グループ 36165029092 にご参加ください。

  • 画像:マルチモーダルが有効になっていないナレッジベースでは、アップロードされた画像をベクトル化したり検索したりすることはできません。

ドキュメントのステータスライフサイクル

ドキュメントは、アップロードされてから検索可能になるまで、次のステータスを経ます。

ステータス説明利用可能な操作
保留中アップロードタスクが受信され、処理を待機しています。ステータスのクエリ、削除。
インデックス作成中ドキュメントが解析、チャンキング、ベクトル化されています。ステータスのクエリ、削除。
完了インデックス作成が完了し、ドキュメントを検索できます。検索、メタデータの更新、削除、チャンクの表示。
失敗インデックス作成に失敗しました。失敗理由の表示、削除、再アップロード。
削除中ドキュメントとそのチャンクが削除されています。削除が完了するまで待機します。

保留中または インデックス作成中ステータスのドキュメントは検索できません。ドキュメントを検索する前に、ステータスが 完了に変わるまで待ってください。ドキュメントが 失敗ステータスになった場合、クエリ操作のレスポンスの failedDetails フィールドに失敗の理由が返されます。

ドキュメントのインポート

AgentStorage ナレッジベースにドキュメントをインポートします。AgentStorage は各ドキュメントを解析してチャンキングし、ベクトルを生成し、インデックスを構築します。同じ ossKey でドキュメントを再度アップロードすると、既存のドキュメントが上書きされます。

ドキュメントは、次の方法でインポートできます。

方法使用場面コンソールオプションSDK メソッド
ローカルファイルのアップロードファイルがローカルコンピューター上にあり、SDK が最初に OSS にアップロードします。[ファイルのアップロード]、[フォルダーのアップロード]upload_documents (Python)、uploadDocuments (TypeScript)
OSS ファイルの追加ファイルはすでに OSS にあります。[OSS からインポート]add_documents (Python)、addDocuments (TypeScript)
OSS ディレクトリからの一括インポートファイルは OSS ディレクトリにあり、システムが再帰的にスキャンします。[OSS からインポート]add_documents (Python)、addDocuments (TypeScript)

必要な認証情報とクライアントは、インポート方法によって異なります。

  • ローカルファイル:アクセスキーペアと、oss_endpoint および oss_bucket_name を含む OSS 設定を指定します。TypeScript では、NodeAgentStorageClient を使用し、ossAccessKeyId および ossAccessKeySecret も指定します。

  • すでに OSS にあるファイル:API キー認証で十分です。AgentStorageClient を使用し、各ファイルの ossKey を指定します。

  • 成功したレスポンスは、すべてのドキュメントが正常にインポートされたことを意味するわけではありません。documentDetails 内のすべてのドキュメントの status フィールドを個別に確認してください。API レスポンスでは、HTTP 200 と code: SUCCESS は、リクエストが受け入れられたことのみを意味します。

  • status: "succeed" は、インデックス作成が完了したことではなく、アップロードタスクが受信されたことを意味します。 インポート操作はこの値を返しますが、ドキュメントのライフサイクルステータスは別の値です。 ドキュメントのインデックス作成の完了を確認するためにポーリングする際は、succeed を使用しないでください。

コンソール

  • AgentStorage コンソールにログインし、管理したいナレッジベースを開き、[ドキュメント管理] に移動して、[ドキュメントのアップロード] をクリックします。

  • インポート方法を選択します。

  • [ファイルのアップロード]:アップロード先 (OSS バケット) を選択し、アップロードするローカルファイルを選択します。

  • [フォルダーのアップロード]:ディレクトリごとにローカルファイルを一括でアップロードします。ディレクトリを再帰的にスキャンするかどうかを選択し、含めるまたは除外するファイル名拡張子を指定できます。

  • [OSS からインポート]:ソースバケットを選択し、OSS から既存のファイルまたはディレクトリをインポートします。

  • OK をクリックし、インポートを開始します。

  • メタデータステップ:ナレッジベースにメタデータスキーマがある場合、アップロードパネルにはステップ3として [メタデータ (オプション)] が表示され、ドキュメントのメタデータフィールドを入力できます。このステップは、メタデータスキーマのないナレッジベースでは利用できません。

  • アップロード制限:アップロードパネルでは、ファイルタイプ、単一ファイルサイズ、およびバッチサイズの制限が適用されます。

  • OSS 認証:OSS 認証プロンプトが表示された場合は、続行する前に認証を完了してください。

SDK

Python

ローカルファイルのアップロード

upload_documents を使用する場合、AgentStorageClient を初期化する際に oss_endpoint と oss_bucket_name の両方を指定する必要があります。そうしないと、ValueError が発生します。

from tablestore_agent_storage import AgentStorageClient

# ローカルファイルをアップロードするために OSS を設定します。SDK はまずファイルを OSS にアップロードし、次にチャンキングとベクトル化を開始します。
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": "田中一郎", "category": "Product documentation"}
        },
        {
            "filePath": "/home/user/docs/faq.docx",
            "metadata": {"author": "鈴木花子", "category": "FAQ"}
        }
    ]
})

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

OSS ファイルの追加

すでに OSS にあるファイルの ossKey を指定します。

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": "田中一郎"}
        }
    ]
})

OSS ディレクトリからの一括インポート

OSS ディレクトリパスを指定します。システムはディレクトリ内のすべてのファイルを再帰的にスキャンします。ファイル名のパターンでフィルタリングするには、inclusionFilters と exclusionFilters を使用します。

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

TypeScript

ローカルファイルのアップロード

ローカルファイルをアップロードするには、NodeAgentStorageClient を使用し、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: '田中一郎', category: 'Product documentation' },
    },
  ],
});

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

OSS ファイルの追加

すでに OSS にあるファイルの ossKey を指定します。

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: '田中一郎' },
    },
  ],
});

OSS ディレクトリからの一括インポート

OSS ディレクトリパスを指定し、ファイル名のパターンでフィルタリングするには inclusionFilters と exclusionFilters を使用します。

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

API

AddDocuments API を呼び出してドキュメントをインポートします。リクエストフィールドとレスポンスの詳細については、「ドキュメントのインポート」をご参照ください。

  • ナレッジベースでサブスペースが有効になっていて、subspace パラメーターを省略した場合、INVALID_PARAMETER が返されます。

インデックス作成ステータスのクエリ

ドキュメントはアップロード後に非同期にインデックスが作成されます。ドキュメントのインデックス作成ステータスをクエリし、ステータスが 完了または 失敗に変わるまでエクスポネンシャルバックオフでポーリングします。

ドキュメントの処理時間は、ファイルサイズ、タイプ、および数量によって異なります。小さなファイルは通常数秒で完了しますが、大きなファイルや一括インポートには数分かかることがあります。

次の例では、fc6ed97f-... をご使用のドキュメントの docId に置き換えてください。docId は、[ドキュメント管理] ページのドキュメントの [詳細] パネルで確認できます。

コンソール

[ドキュメント管理] リストで、[ステータス] 列の各ドキュメントの現在のステータスを確認できます。ドキュメントをすばやく見つけるには、リストの上のステータスフィルターを使用できます:[すべて]、[保留中]、[インデックス作成中]、[完了]、[失敗]、または [削除中]。[操作] 列で 詳細 をクリックすると、ドキュメント ID、OSS パス、ステータス、およびチャンク数が表示されます。

SDK

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):
    """エクスポネンシャルバックオフを使用してドキュメントのステータスをポーリングし、インデックス作成が完了するのを待ちます。"""
    interval = 3
    while True:
        resp = client.get_document({
            "knowledgeBaseName": kb_name,
            "docId": doc_id
        })
        status = resp["data"][0]["status"]
        if status == "Completed":
            print(f"インデックス作成が完了しました。チャンク数: {resp['data'][0].get('chunkNum', 'N/A')}")
            return resp
        elif status == "Failed":
            raise Exception(f"インデックス作成に失敗しました: {resp['data'][0].get('failedDetails')}")
        print(f"現在のステータス: {status}。{interval} 秒後に再試行します...")
        time.sleep(interval)
        interval = min(interval * 2, max_interval)

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

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(`インデックス作成が完了しました。チャンク数: ${doc.chunkNum ?? 'N/A'}`);
      return resp;
    } else if (doc.status === 'Failed') {
      throw new Error(`インデックス作成に失敗しました: ${doc.failedDetails}`);
    }
    console.log(`現在のステータス: ${doc.status}。${interval} 秒後に再試行します...`);
    await new Promise((r) => setTimeout(r, interval * 1000));
    interval = Math.min(interval * 2, maxInterval);
  }
}

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

API

GetDocument API を呼び出して、ドキュメントのインデックス作成ステータスをポーリングします。フィールドの詳細については、「ドキュメントのクエリ」をご参照ください。

ドキュメントのクエリ

指定されたドキュメントの詳細 (処理ステータス、チャンク数、メタデータなど) をクエリします。docId または ossKey のいずれかを指定します。次の例では、fc6ed97f-... をご使用のドキュメントの docId に置き換えてください。

コンソール

[ドキュメント管理] リストで、クエリするドキュメントの [操作] 列にある 詳細 をクリックします。パネルには、ドキュメント ID、名前、OSS パス、ステータス、チャンク数、サブスペース、ETag、作成時刻、更新時刻が表示されます。

SDK

同じ ossKey が作成、削除、再作成のプロセスを経ると、get_document は履歴レコードを含む複数のレコードを返すことがあります。status フィールドを使用して有効なドキュメントを特定し、ステータスが 完了のレコードを選択してください。

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"ステータス: {doc['status']}, チャンク数: {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(`ステータス: ${doc.status}, チャンク数: ${doc.chunkNum ?? 'N/A'}`);

API

GetDocument API を呼び出してドキュメントの詳細を取得します。フィールドの詳細については、「ドキュメントのクエリ」をご参照ください。

ドキュメントの一覧表示

AgentStorage ナレッジベース内のドキュメントをページごとに一覧表示します。

コンソール

ナレッジベースの [ドキュメント管理] ページに移動します。リストには、ドキュメント名、作成時刻、更新時刻、チャンク数、およびステータスが表示されます。ドキュメントをすばやく見つけるには、リストの上にあるステータスフィルターを使用できます:[すべて]、[保留中]、[インデックス作成中]、[完了]、[失敗]、または [削除中]。

SDK

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.list_documents({
    "knowledgeBaseName": "product_docs_kb",
    "maxResults": 20
})
for doc in resp["data"]["documentDetails"]:
    print(f"[{doc['status']}] {doc['ossKey']} (チャンク数: {doc.get('chunkNum', '-')})")

# 次のページを取得
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} (チャンク数: ${doc.chunkNum ?? '-'})`);
}

API

ListDocuments API を呼び出してドキュメントを一覧表示します。フィールドの詳細については、「ドキュメントの一覧表示」をご参照ください。

  • maxResults のデフォルト値は 10 で、最大値は 1000 です。

  • subspace パラメーターは最大 10 個の値のリストをサポートします。上限を超えるとエラーが返されます。

ドキュメントメタデータの更新

SDK または API を使用して、指定されたドキュメントのメタデータを更新します。メタデータを更新できるのは、完了ステータスのドキュメントのみです。他のステータスのドキュメントに対してこの操作を呼び出すと、エラーが返されます。

  • 上書き形式の更新:指定した値が元のメタデータを完全に置き換えます。1 つのフィールドのみを更新する場合でも、すべてのフィールドを含める必要があります。

  • メタデータのクリア:"metadata": null を渡すと、すべてのメタデータがクリアされます。metadata フィールドを省略すると、元の値が保持されます。

  • サイズとフィールドの制限:キーと値を含むメタデータの合計サイズは 4 KB に制限されています。最大 200 フィールドまで指定できます。

  • 日付形式:メタデータの日付フィールドは、yyyy-MM-dd HH:mm:ss などのサポートされている形式を使用する必要があります。サポートされていない形式を使用すると、ドキュメントは 失敗ステータスになります。

SDK

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": "田中一郎", "category": "Technical documentation", "version": 2}
})

print(f"更新ステータス: {resp['data']['updateStatus']}")  # UPDATED または 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: '田中一郎', category: 'Technical documentation', version: 2 },
});

console.log(`更新ステータス: ${resp.data.updateStatus}`); // UPDATED または NO_OP

API

UpdateDocument API を呼び出してドキュメントのメタデータを更新します。フィールドの詳細については、「ドキュメントの更新」をご参照ください。

ドキュメントの削除

ドキュメントを削除すると、そのすべてのチャンクも削除されます。この操作は元に戻せません。

コンソール

[ドキュメント管理] リストで、1 つ以上のドキュメントを選択して [一括削除] をクリックするか、[操作] 列の 削除 をクリックして単一のドキュメントを削除します。確認ダイアログボックスで、OK をクリックします。

SDK

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"}
    ]
})

# 各削除結果を個別に確認します
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' },
  ],
});

// 各削除結果を個別に確認します
for (const detail of resp.data.documentDetails) {
  console.log(`${detail.ossKey}: ${detail.status}`);
}

API

DeleteDocuments API を呼び出してドキュメントを削除します。フィールドの詳細については、「ドキュメントの削除」をご参照ください。

関連ドキュメント