AgentStorage ナレッジベース内のドキュメントを管理します。これには、インポート、クエリ、一覧表示、更新、削除の操作が含まれます。ローカルコンピューターまたは Object Storage Service (OSS) からファイルをインポートし、アップロードから検索まで各ドキュメントを追跡できます。
前提条件
AgentStorage インスタンス、およびそのアクセスエンドポイントとインスタンス名。 詳細については、「AgentStorage インスタンスを作成する」をご参照ください。
ナレッジベース。詳細については、「ナレッジベースの管理」をご参照ください。
AgentStorage SDK がインストールされ、認証済みであること。手順については、「Agent Storage SDK」をご参照ください。
ローカルコンピューターからドキュメントをアップロードするには、インスタンスと同じリージョンにある OSS バケットと、完了した OSS 認証が必要です。SDK を初期化する際に、アクセスキーペア、OSS エンドポイント、バケット名などの OSS 設定も指定します。
(条件付き) 画像を保存し、マルチモーダル検索を使用するには、ナレッジベースでマルチモーダルが有効になっている必要があります。マルチモーダルはナレッジベースの作成時にのみ有効にでき、一度有効にするとこの設定は変更できません。
(条件付き) ナレッジベースでサブスペースが有効になっている場合は、すべてのインポートおよび一覧表示リクエストで
subspaceパラメーターを指定する必要があります。(条件付き) アップロード中にドキュメントのメタデータを入力するには、ナレッジベースにメタデータスキーマが設定されている必要があります。
サポートされているドキュメント形式
AgentStorage ナレッジベースは、次のファイル形式をサポートしています。
| タイプ | ファイル名拡張子 |
.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_OPTypeScript
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_OPAPI
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 を呼び出してドキュメントを削除します。フィールドの詳細については、「ドキュメントの削除」をご参照ください。
関連ドキュメント
ドキュメントチャンクの表示と調整については、「ナレッジチャンクの管理」をご参照ください。
ナレッジベースの作成と設定については、「ナレッジベースの管理」をご参照ください。