博客 / 詳情

返回

基於seekdb，教你從零開始構建智能搜書應用

seekdb 是什麼樣的數據庫？

最近體驗了一下 seekdb，先説幾點感受。

第一，是單節點輕量化設計，在我的 macbook 上通過 docker 桌面端部署可以輕鬆跑起來，在 Linux 環境下直接用 pip 安裝，據説不久就會支持 macOS/windows 系統，連 docker 都省了，直接通過命令安裝。

第二，它是一體化設計，原生融合關係型、向量、全文、JSON、GIS 五種類型的數據，所有索引在同一事務內原子更新，這意味着 Zero Data Lag 和嚴格的 ACID，徹底規避傳統 CDC 同步導致的延遲與不一致問題。

第三，它是一個 AI-Native 數據庫，體現在它內置有 embedding 模型和 AI Function，單條 SQL 實現向量 + 全文 + 標量過濾的聯合查詢，不需要再寫大量的複雜的膠水層邏輯拼合各種技術棧，直接驅動 RAG 流程（如圖）。

第四，它的 API 是 Schema-free 的設計，也就是直接寫入，不要求預先定義嚴格的表結構。

第五，它完全兼容 MySQL，意味着傳統數據庫可以輕鬆進行 AI 化升級。

第六點同樣很重要，它是在 Apache 2.0 協議許可下開源，同時它有 OceaBase 的基因。長期發展有保障，只會越來越成熟。

教程：基於seekdbb實現智能搜書應用

本教程將帶你從零開始，基於 seekdb 實現一個「智能搜書」的程序，演示如何實現語義搜索和混合搜索等 seekdb 的主要能力。

教程具體做的事情包括：

  1. 數據導入
  • 從 csv 文件導入 seekdb
  • 支持數據分批導入
  • 自動將書籍的文本信息轉換為 384 維向量嵌入
  1. 用到三種搜索能力
  • 語義搜索：基於向量相似度，用自然語言查詢找到語義相關的書籍。
  • 元數據過濾：按評分、類型、年份、價格等字段精確過濾。
  • 混合搜索：結合語義搜索 + 元數據過濾，使用 RRF 算法融合排序。
  1. 索引優化
  • 創建 HNSW 向量索引提升語義搜索性能。
  • 元數據生成列索引（從 JSON 提取字段創建索引）
  1. 技術棧
  • 數據庫: seekdb，pyseekdb（seekdb 的 Python SDK），pymysql
  • 數據處理工具：pandas

三、準備工作

1. 安裝 OrbStack

OrbStack 是一個輕量級的 Docker 替代品，專為 Mac 優化，啓動速度快且資源佔用低。用它本地部署 seekdb。

第一步，使用 Homebrew 安裝（推薦）：

brew install orbstack

或從官網下載：訪問 https://orbstack.dev 下載安裝包。

第二步，啓動 OrbStack：

# 啓動 OrbStack
open -a OrbStack

# 驗證安裝
orb version

2. 部署 seekdb 鏡像

如果卡住，先去 orbstack 配置 docker 國內鏡像源（鏈接）。

# 拉取 SeekDB 鏡像
docker pull oceanbase/seekdb:latest

# 啓動 SeekDB 容器
docker run -d \
  --name seekdb \
  -p 2881:2881 \
  -e MODE=slim \
  oceanbase/seekdb:latest

# 查看容器狀態
docker ps | grep seekdb

# 查看日誌（確保服務啓動成功）
docker logs seekdb

等待約 30 秒讓 seekdb 完全啓動。你可以通過 docker logs -f seekdb 查看啓動日誌，看到 "boot success" 表示啓動完成。

3. 下載數據集

下載數據集：https://www.kaggle.com/datasets/sootersaalu/amazon-top-50-bestselling-books-2009-2019

將數據集命名為： bestsellers_with_categories.csv，有 550 條 amazon 歷史暢銷書的記錄，內容如圖：

4. 下載教程代碼

git clone https://github.com/kejun/demo-seekdb-hybridsearch.git

項目結構：

demo-seekdb-books-hybrid-search/
├── database/
│   ├── db_client.py      # 數據庫客户端封裝
│   └── index_manager.py  # 索引管理器
├── data/
│   └── processor.py      # 數據處理器
├── models/
│   └── book_metadata.py  # 書籍元數據模型
├── utils/
│   └── text_utils.py     # 文本處理工具
├── import_data.py        # 數據導入腳本
├── hybrid_search.py      # 混合搜索演示
└── bestsellers_with_categories.csv  # 數據文件

創建 Python 虛擬環境：

# 創建虛擬環境
python3 -m venv venv

# 激活虛擬環境
source venv/bin/activate   # macOS/Linux
# 或
.\venv\Scripts\activate    # Windows

安裝依賴：

pip install -r requirements.txt

執行效果

執行python import_data.py導入數據。可以看到整個過程：加載數據文件 → 連接數據庫 → 創建數據庫 → 創建集合 → 分批導入數據 → 創建元數據索引（注：seekdb 目前只支持對 embedding 列創建 HNSW 索引，對 document 列創建全文索引，對元數據字段創建暫不支持，據介紹在計劃中）。

seekdb 採用的是 schema-free 的接口設計，比如在data/processor.py中，調用collection.add()時直接傳入任意字典：

collection.add(
    ids=valid_ids,
    documents=valid_documents,
    metadatas=valid_metadatas  # 直接傳入字典列表，無需預定義 schema
)

完整結果（有所精簡）如下：

正在加載數據文件: bestsellers_with_categories.csv
數據加載完成!
- 總行數: 550
- 總列數: 7
- 列名: Name, Author, User Rating, Reviews, Price, Year, Genre
- 加載耗時: 0.01 秒

正在連接數據庫...
主機: 127.0.0.1:2881
數據庫: demo_books
集合: book_info
數據庫已就緒
數據庫連接成功

正在創建/重建集合...
集合名稱: book_info
向量維度: 384
距離度量: cosine
集合創建成功

正在處理數據...
數據預處理完成!
- 總記錄數: 550
- 驗證錯誤數: 0
- 處理耗時: 0.05 秒

正在導入數據到集合...
- 批次大小: 100
- 總批次數: 6
- 開始導入...

導入進度: 100%|█████████████████████████████████████| 6/6 [00:53<00:00,  8.97s/批次]

數據導入完成!
- 導入耗時: 53.83 秒
- 平均速度: 10 條/秒

正在創建元數據索引...
- 索引字段: genre, year, user_rating, author, reviews, price
索引創建完成!
- 創建耗時: 3.81 秒

數據導入流程完成!
總耗時: 59.64 秒
導入記錄數: 550
數據庫: demo_books
集合: book_info

導完數據，可以直接用 mysql client 或安裝 obclient（鏈接） 在終端上查詢數據庫。

# 進入 SeekDB 容器
docker exec -it seekdb bash

# 使用 MySQL 客户端連接（SeekDB 兼容 MySQL 協議）

mysql -h127.0.0.1 -P2881 -uroot

book_info是 seekdb 的 collection，對應底層的表名是c$v1$book_info：

-- 查看所有數據庫
SHOW DATABASES;

-- 切換到 demo 數據庫
USE demo;

-- 查看所有表（集合）
SHOW TABLES;

-- 查看集合結構
DESC c$v1$articles;

-- 查詢集合數據
SELECT * FROM c$v1$articles LIMIT 10;

-- 統計記錄數
SELECT COUNT(*) FROM c$v1$articles;

-- 退出
EXIT;

看一下表結構DESC c$v1$book_info：

看一下創建的索引：

（注意：pyseekdb 目前不直接支持對元數據列創建索引，所以項目通過 pymysql + SQL DDL 來實現元數據索引功能。據説在下個 pyseekdb 版本中將會支持自動對元數據字段進行索引）

接一下，執行搜索python hybrid_search.py。 seekdb 內置的 embedding 模型是sentence-transformers/all-MiniLM-L6-v2，向量維度最大 384，要想獲得更好的效果還是要配置外部的模型服務。

混合搜索是 seekdb 的 killer feature。它同時執行全文檢索和向量檢索，然後使用 RRF (倒數排名融合) 算法合併。

看具體代碼示例，query_params定義的是全文搜索“勵志”（“inspirational”），同時用元數據中的用户評分（user_rating）過濾（評分大於等於 4.5）。knn_params是語義搜索，query_texts是句雞湯“勵志人生忠告”（"inspirational life advice"），用同樣的用户評分做過濾。

代碼片斷：

query_params = {
    "where_document": {"$contains": "inspirational"},
    "where": {"user_rating": {"$gte": 4.5}},
    "n_results": 5
}
knn_params = {
    "query_texts": ["inspirational life advice"],
    "where": {"user_rating": {"$gte": 4.5}},
    "n_results": 5
}

results = collection.hybrid_search(
    query=query_params,
    knn=knn_params,
    rank={"rrf": {}},
    n_results=5,
    include=["metadatas", "documents", "distances"]
)

可以 vibe-eval 一下結果，感覺是挺準的。完整執行結果（有所精簡）如下：

=== 語義搜索 ===
Query: ['self improvement motivation success']

語義搜索 - 找到 5 條結果:

[1] The 7 Habits of Highly Effective People: Powerful Lessons in Personal Change
    作者: Stephen R. Covey
    評分: 4.6
    評論數: 9325
    價格: $24.0
    年份: 2011
    類型: Non Fiction
    相似度距離: 0.5358
    相似度: 0.4642

（省略其它......）


=== 混合搜索 (評分≥4.5) ===
Query: {'where_document': {'$contains': 'inspirational'}, 'where': {'user_rating': {'$gte': 4.5}}, 'n_results': 5}
KNN Query Texts: ['inspirational life advice']

混合搜索 (評分≥4.5) - 找到 5 條結果:

[1] Mindset: The New Psychology of Success
    作者: Carol S. Dweck
    評分: 4.6
    評論數: 5542
    價格: $10.0
    年份: 2014
    類型: Non Fiction
    相似度距離: 0.0159
    相似度: 0.9841
    
（省略其它......）


=== 混合搜索 (Non Fiction) ===
Query: {'where_document': {'$contains': 'business'}, 'where': {'genre': 'Non Fiction'}, 'n_results': 5}
KNN Query Texts: ['business entrepreneurship leadership']

混合搜索 (Non Fiction) - 找到 5 條結果:

[1] The Five Dysfunctions of a Team: A Leadership Fable
    作者: Patrick Lencioni
    評分: 4.6
    評論數: 3207
    價格: $6.0
    年份: 2009
    類型: Non Fiction
    相似度距離: 0.0164
    相似度: 0.9836

（省略其它......）


=== 混合搜索 (Fiction, 2015年後, 評分≥4.0) ===
Query: {'where_document': {'$contains': 'fiction'}, 'where': {'$and': [{'year': {'$gte': 2015}}, {'user_rating': {'$gte': 4.0}}, {'genre': 'Fiction'}]}, 'n_results': 5}
KNN Query Texts: ['fiction story novel']

混合搜索 (Fiction, 2015年後, 評分≥4.0) - 找到 5 條結果:

[1] A Gentleman in Moscow: A Novel
    作者: Amor Towles
    評分: 4.7
    評論數: 19699
    價格: $15.0
    年份: 2017
    類型: Fiction
    相似度距離: 0.0154
    相似度: 0.9846

（省略其它......）

=== 混合搜索 (評論數≥10000) ===
Query: {'where_document': {'$contains': 'popular'}, 'where': {'reviews': {'$gte': 10000}}, 'n_results': 10}
KNN Query Texts: ['popular bestseller']

混合搜索 (評論數≥10000) - 找到 10 條結果:

[1] Twilight (The Twilight Saga, Book 1)
    作者: Stephenie Meyer
    評分: 4.7
    評論數: 11676
    價格: $9.0
    年份: 2009
    類型: Fiction
    相似度距離: 0.0143
    相似度: 0.9857

[2] 1984 (Signet Classics)
    作者: George Orwell
    評分: 4.7
    評論數: 21424
    價格: $6.0
    年份: 2017
    類型: Fiction
    相似度距離: 0.0145
    相似度: 0.9855

[3] Last Week Tonight with John Oliver Presents A Day in the Life of Marlon Bundo (Better Bundo Book, LGBT Childrens Book)
    作者: Jill Twiss
    評分: 4.9
    評論數: 11881
    價格: $13.0
    年份: 2018
    類型: Fiction
    相似度距離: 0.0147
    相似度: 0.9853

（省略其它......）

Vibe Coding 友好

如果你用 Cursor 或 Claude Code 開發一定裝了 context7-mcp，它會查詢最新的 API 文檔、代碼示例等，是#Vibecoding 的最佳伴侶。我看到 seekdb 也被添加到 Context7 中：

  • seekdb:https://context7.com/oceanbase/seekdb
  • pyseekdb: https://context7.com/oceanbase/pyseekdb 如果還沒裝牆裂推薦安裝：
{
"mcpServers": {
    "context7": {
      "command": "npx",
      "args": [
        "-y",
        "@upstash/context7-mcp",
        "--api-key",
        "<你在context7上創建的apiKey>"
      ]
    },
  (...)
  }
}

裝完之後，你就可以邊學邊用了。

希望這篇教程有助於你更順利的上手#seekdb。Enjoy!

AI
user avatar
0 位用戶收藏了這個故事！

發佈 評論

Some HTML is okay.