TgWitness參考資料 / 存檔與整合功能
Telegram · 全文搜尋
可透過詞形、精確短語、網域及 @用戶名 搜尋已儲存的訊息，結果依最符合的順序排列，且索引與簽名日誌綁定。
檔案分析 · 本地 OCR 與文字轉錄 · 維基
預覽。在「日誌」中，於搜尋欄旁選擇「最佳匹配 · 詞形變體」。 搜尋結果依 BM25 演算法排序，並會匹配同一詞彙的其他詞形： 搜尋「перевод」會找到「переводом」和「переводы」，搜尋「transfer」會找到「transfers」，而中文 短語則會以不帶空格的形式被檢索。選擇「最新優先 · 精確文字」可維持先前 針對整個記錄進行的子字串搜尋。
索引屬衍生資料。它由簽名日誌重建而成，本身從未經過簽名， 也絕不會被導出。原始記錄不會被更改。
搜尋語法#
| 撰寫 | 搜尋結果 |
|---|---|
перевод карта |
同時包含這兩個詞彙的記錄，形式不限 |
"переводом на карту" |
請按此順序保留確切的詞句 |
бонус OR подарок |
任一詞彙 |
перевод -казино |
不含排除詞的記錄 |
example.com |
該網域及其子網域，包括隱藏連結和按鈕網址在內 |
@username, t.me/username |
該帳號的提及與連結，以及其發送的訊息 |
#tag |
主題標籤 |
+79991234567、一個錢包地址、一個電子郵件地址 |
以文字或連結形式呈現相同內容 |
from:@username, from:123456 |
來自該發送者的訊息 |
chat:-1001234567890 |
一個聊天室；它只能限制您自身的存取權限 |
id:42 |
訊息 42 的儲存版本 |
since:2026-01-01 until:2026-01-31 |
觀察期間；未標示時間的日期代表整日 |
kind:edited |
僅限編輯 (new, snapshot, edited, recovered) |
source:ocr, source:transcription, source:all |
以識別出的文字取代訊息，或與訊息並存 |
當存在其他單字時，介詞及其他功能詞將被忽略。 混入單字中的相似字母（例如西文字母「a」出現在西里爾字母單字中）、全寬 及裝飾性 Unicode 字母，以及不可見字元，均會被標準化。
語言#
系統會根據每筆記錄中的腳本和字母來偵測語言：
| 腳本 | 匹配 |
|---|---|
| 西里爾字母 | 使用 pymorphy3 處理俄語與烏克蘭語詞幹。若未啟用可選的烏克蘭語詞典，則會使用輕量級的烏克蘭語詞幹分析器 |
| 拉丁文 | 英文 Snowball 詞幹提取器；忽略音標符號 |
| 中文、日文、韓文、泰文、老撾文、高棉文、緬甸文 | 重疊字元對：搜尋時不包含空格。中文查詢會使用 jieba 進行分詞 |
| 其他腳本 | 精確詞句 |
烏克蘭語辭典 (pymorphy3-dicts-uk) 依據 GPL-3.0 授權發佈，因此
預設不會安裝。請使用 pip install "tgwitness[uk-dictionary]"；
索引模組會偵測到新的分析器並自動重新建構。
索引的存放位置#
| 模式 | 儲存 | 使用說明 |
|---|---|---|
| 儲存於磁碟（預設） | search/fulltext.sqlite3 位於工作區目錄中 |
大型存檔；重啟後仍能保留資料 |
| 僅限記憶體中 | 磁碟上不留任何資料；每次啟動時皆重新建置 | 磁碟上不會存有訊息內容的任何衍生副本 |
| 關閉 | 無索引；最新內容優先 · 保留原始文字 | 最低安裝需求 |
主要管理員可於「日誌」→「篩選器」→「搜尋索引」中
為每個工作區選擇模式。 TGWITNESS_FULLTEXT=disk|memory|off 並為
未自行設定的空間設定預設值。切換至「記憶體」或「關閉」將刪除該檔案。
索引檔案與日誌享有相同的保護措施：它存放於私有資料
目錄中。該檔案未經加密，且不包含在備份或異地副本之中。
新記錄會在數秒內於後台完成索引；搜尋時也會優先索引 短暫的歷史記錄，因此剛儲存的記錄也能被找到。現有的日誌會在 更新後完成索引，且不會阻塞控制面板；在此之前，搜尋結果涵蓋 已索引的記錄，而日誌會顯示進度。重建索引時會從 第一筆記錄開始重新進行。
python -m tgwitness index status --data-dir data/live
python -m tgwitness index rebuild --data-dir data/live --jsonrebuild 需停止該面板（否則退場代碼為 3）。若使用 --json，
標準輸出僅顯示結果；進度訊息則輸出至標準錯誤。
結果與簽名日誌#
索引會儲存其所涵蓋之最後一筆日誌記錄的序號與雜湊值， 並在開啟日誌時將其與日誌內容進行比對。若日誌遭替換、還原或編輯， 則會觸發索引重建。每次回應都會回報此位置，而每次查詢結果皆 透過其序號從簽名日誌中讀取：索引僅決定 應顯示哪些記錄及顯示順序，絕不涉及記錄內容。聊天室存取權限僅適用於 日誌本身的聊天室欄位，不適用於索引內容。
已識別的文字#
OCR 結果與轉錄內容仍保留於其加密的原始檔中。其索引僅存在於
記憶體中，並會在辨識任務完成時重新建置。當出現匹配結果時，該結果會顯示於其
media.saved 記錄上會顯示一個匹配結果，標記為「機器識別」，並附有引擎、模型及
摘錄內容；該內容絕不會以 Telegram 傳送的文字形式呈現。同一索引亦供
「搜尋已識別文字」功能使用，該功能同時仍可匹配純文字子字串。
存取#
「聊天室範圍」存取僅會搜尋來自該聊天室的記錄，包括其附件中
被識別的文字。 chat: 以及其他篩選條件僅能進一步縮小該資料集範圍。顯示給範圍內存取的索引狀態
會省略日誌總數。僅有主要管理員才能變更
模式或重建索引。
請諮詢檔案庫與 MCP#
當索引建立完成後，查詢功能將從此索引擷取來源： 選定聊天室中的最佳匹配結果，且每則已儲存的文字僅計入一次。最多會傳送 24 個來源；長篇文字會以匹配內容為界截斷，並標記為「截斷」。 關於近期變更、單則訊息的儲存版本，以及在 索引仍在建立期間的搜尋，均使用先前的按時間順序檢索方式。預覽 畫面會顯示所使用的檢索方法。
MCP 客戶端可呼叫 search_messages 透過 ranked=true ，並透過
next_offset。範圍限定連線僅會接收其對應的聊天內容。
排序分頁最多涵蓋前 1,000 筆結果，無論頁面大小為何。請縮小查詢範圍、聊天室或時間範圍，以檢視更多匹配結果。按「最新優先」搜尋時，系統會在選取各頁面之前，先將訊息、OCR 及轉錄結果依此順序排列。
依賴項#
| 套件 | 授權條款 | 原因 |
|---|---|---|
| pymorphy3、pymorphy3-dicts-ru、DAWG2-Python | MIT | 俄語與烏克蘭語詞幹；詞典於本地載入 |
| snowballstemmer | BSD-3 條款 | 英文詞幹，純 Python |
| jieba | MIT | 中文查詢分詞，純 Python 實作（僅提供原始碼發行版） |
| pymorphy3-dicts-uk（可選） | GPL-3.0 | 完整的烏克蘭語詞典 |
SQLite FTS5 需搭配 unicode61 分詞器；此功能已包含於
當前 Python 建置版本的 SQLite 中。若未啟用，最佳匹配搜尋將回報該功能不可用。
基準測試#
python tools/bench_fulltext.py --messages 1000000 --work <empty directory>建立一個包含俄語、烏克蘭語、英語、
中文及日語訊息的確定性簽名日誌，內容涵蓋 200 個聊天室中的連結與識別碼，並建立索引
以及測量典型搜尋所需時間（50 筆結果，7 次執行中的中位數）。
測試環境：Windows 11、Intel Core i9-13900K、128 GB 記憶體、Python 3.12.10、SQLite
3.49.1，資料儲存於 exFAT 磁碟機，分析器 fulltext-v1+pymorphy3-ru+light-uk+snowball-en:
| 度量 | 結果 |
|---|---|
| 簽名日誌 | 1,000,000 則訊息，1.50 GiB，於 19 分鐘內寫入 |
| 從日誌建立索引 | 71 秒，約每秒 14,141 則訊息 |
| 索引檔案 | 58 MiB，佔日誌的 3.8% |
| 在新記錄生成後立即進行搜尋 | 中位數 8 毫秒，第 95 百分位數 9 毫秒 |
| 先前子字串搜尋，同一日誌 | перевод 3.2 秒， 银行转账 2.6 秒， verify-account.example 2.6 秒 |
| 搜尋 | 匹配的記錄 | 最佳匹配、中位數 | p95 | 最新優先，中位數排序 |
|---|---|---|---|---|
常見詞彙及其詞形： перевод |
134,403 | 82 毫秒 | 85 毫秒 | 7 毫秒 |
兩個字： оплата карта |
28,996 | 43 毫秒 | 43 毫秒 | 14 毫秒 |
生僻詞： розыгрыш подарок |
28,881 | 42 毫秒 | 47 毫秒 | 13 毫秒 |
精確短語： "переказ коштів на картку" |
不計入 | 35 毫秒 | 36 毫秒 | 6 毫秒 |
網域及其子網域： verify-account.example |
12,435 | 17 毫秒 | 17 毫秒 | 3 毫秒 |
@使用者名稱： @support_desk_bot |
10,331 | 15 毫秒 | 16 毫秒 | 3 毫秒 |
中文（無空格）： 银行转账 |
17,691 | 23 毫秒 | 24 毫秒 | 3 毫秒 |
日文： リンク |
16,603 | 23 毫秒 | 25 毫秒 | 3 毫秒 |
英文詞幹： withdrawal |
27,775 | 26 毫秒 | 26 毫秒 | 2 毫秒 |
或與排除： бонус OR подарок -казино |
268,034 | 190 毫秒 | 193 毫秒 | 19 毫秒 |
聊天過濾器： chat:-1000000000007 перевод |
652 | 9 毫秒 | 9 毫秒 | 6 毫秒 |
時間範圍篩選器： since:2026-01-01 until:2026-01-31 выплата |
115,732 | 155 毫秒 | 156 毫秒 | 81 毫秒 |
系統會依排名順序，逐一對候選結果進行字面比對，直到頁面 填滿為止，因此其總數不計入統計。搜尋時間會隨匹配記錄的數量增加而增長； 縮小聊天室範圍或時間區間，可加快廣泛搜尋的速度。合成語料庫重複 使用少量詞彙，因此常見詞彙所匹配的記錄數量遠多於真實聊天記錄。