Hane Platform

文書と検索

文書のアップロード、マルウェアの検査、本文の取り出し（OCR・変換）、全文検索と意味検索、読める人の決まり、削除と hold を説明します。

このページでは、Hane に文書を入れてから、検索して Agent や人が読むまでの流れを説明します。誰がどの文書を読めるかと、消すときに何が起きるかも扱います。

文書とバージョン

文書は、原本のファイルとそのバージョンの組です。同じ文書に新しいファイルを送ると、前のバージョンを上書きせずに次のバージョンを足します。原本の保存先のキーは API では返しません。

受け付ける形式は次のとおりで、1 ファイル 10 MiB までです。

形式	扱い
PDF	埋め込んだ文字を取り出して索引にします。文字のないページは OCR で読みます
UTF-8 のテキスト	確定と同時に索引に入り、検査を待たずに探せます
Word・Excel・PowerPoint（新旧の形式）	原本はそのまま保管し、索引と抽出には PDF に変換した派生物を使います
ZIP	`expand` で展開し、中のファイルを 1 件ずつ文書にします（100 件・合計 50 MiB まで）

アップロードの流れ

アップロードは、準備・送信・確定の 3 段に分かれています。確定のときに、実物のサイズ・SHA-256・形式を確かめます。

POST /v1/documents/upload-sessions に、ファイル名・content_type・サイズ・SHA-256 を送ってセッションを作ります。公開範囲（visibility）もここで決めます。
PUT /v1/documents/upload-sessions/{id}/content に原本を送ります。確定するまでは隔離した場所に置きます。
POST /v1/documents/upload-sessions/{id}/complete で確定します。原本とバージョンを保存し、マルウェアの検査を予約します。

同じ公開範囲の中に、SHA-256 が同じ文書がすでにあれば、新しい文書を作らずに受け取りの記録（receipts）だけを足します。

ファイルを置く口は、ほかにもあります。

プロジェクトごとのメールアドレスへ書類を転送する（GET /v1/documents/intake-address）プレビュー
外部の保管場所を同期する（documents/v1alpha1 の DocumentSource）プレビュー

転送したメールの添付は 1 件ずつ文書になり、プロジェクトに公開されます。外部の保管場所の同期には、原本のコピーを持つ取り込み（ingest）と、本文と索引だけを持つ参照だけ（reference）があります。参照だけの文書は、値の根拠には使えません。

検査と本文の取り出し

確定したバージョンは、非同期にマルウェアの検査をします。検査状態は queued・scanning・clean・infected・failed のどれかで、原本をダウンロードできるのは clean のものだけです。検査サービスが止まっても保存は止めず、自動で再試行します。

検索に使う本文は、形式ごとに取り出します。進み具合は index_status で分かります。

`index_status`	意味
`queued`	取り出しを待っています
`indexed`	検索と読み取りに使えます
`needs_ocr`	文字のない PDF で、その環境に OCR がありません
`needs_conversion`	Office の書類で、その環境に変換がありません
`failed`	読めませんでした

本文は GET /v1/documents/{id}/versions/{version}/pages で、ページ番号付きで読めます。原本を渡さずに中身を読むための口で、Agent の documents.read_pages もこれを使います。OCR で読んだページには、ページごとの信頼度と行の位置が付きます。

検索

POST /v1/documents/search は、読める文書のいまのバージョンだけを探します。結果はページの中のチャンク（800 文字）で返り、一致の強い順に並びます。

`mode`	探し方	提供状況
`keyword`（既定）	空白で区切ったすべての語を含むチャンクを探す全文検索。NFKC で正規化し、大文字と小文字を区別しません	提供しています
`summary`	ページごとの最初の文から作った要約を探します。ページをまたいだ語も見つかります	提供しています
`semantic`	チャンクの埋め込みが問いに近いものを探す意味検索	プレビュー
`hybrid`	全文検索と意味検索の順位をまとめます	プレビュー

const hits = await unwrap(
  client.POST("/v1/documents/search", {
    body: { query: "中途解約 違約金", mode: "keyword", limit: 20 },
  }),
);

意味検索を有効にしていない環境では、semantic と hybrid は CONFLICT を返します。意味検索の索引は世代ごとに作り直し、評価を通してから切り替えます（/v1/documents/search-index。documents:search-index.manage が必要）。

感染を検出したバージョンは、検索の結果に出ません。どの検索でも、返す直前に読む権限といまのバージョンを確かめ直します。

読める人

文書の公開範囲は 2 つです。

`visibility`	読める人
`private`（既定）	アップロードした本人だけ
`project`	プロジェクトのメンバーのうち、`documents:read` を持つ人

操作ごとに必要な権限は分かれています。読むのは documents:read、足すのは documents:write、原本を落とすのは documents:download、消すのは documents:delete、残す指定は documents:hold です。索引や要約のような派生物も、元の文書の権限を迂回しません。

抽出の候補

索引を作るときに、有効な抽出の定義（ExtractionSchema）で、書類から項目の値を抜き出します。これが抽出の候補で、ページと引用を持ちます。候補は人が確かめるまで台帳の値になりません。確定（POST /v1/documents/facts/{id}/confirm）できるのは利用者だけで、AI やサービスアカウントは確定できません。定義の書き方は文書を使うを見てください。

削除と hold

DELETE /v1/documents/{id} は、索引・要約・確かめていない候補をすぐに外し、直後の検索から返さないようにします。そのうえで原本と本文を消します。

文書に hold をかけている間は、削除を受け付けても原本・本文・抽出の記録を消さずに残します。hold を外したときに消します。何を消し、何を残したかは、派生物ごとに削除の追跡（GET /v1/documents/{id}/disposal）で確かめられます。

次に読む