{/* Trang này được tạo tự động từ SKILL.md của kỹ năng bởi website/scripts/generate-skill-docs.py. Chỉnh sửa nguồn SKILL.md, không phải trang này. */}

Qmd

Tìm kiếm cục bộ cơ sở kiến thức cá nhân, ghi chú, tài liệu và bản ghi cuộc họp bằng cách sử dụng qmd — một công cụ truy xuất kết hợp với BM25, tìm kiếm vectơ và sắp xếp lại LLM. Hỗ trợ tích hợp CLI và MCP.

Siêu dữ liệu kỹ năng


Nguồn	Tùy chọn — cài đặt với
`Hermes skills install official/research/qmd
`
Đường dẫn

optional-skills/research/qmd ` | | Phiên bản |

, `Knowledge-Base

, `RAG

, `Notes

, `MCP

, Local-AI | | Kỹ năng liên quan | XPROTECTX33XPROTECTX, XPROTECTX34XPROTECTX, XPROTECTX35XPROTECTX |

Tham khảo: đầy đủ SKILL.md

thông tin

Sau đây là định nghĩa kỹ năng đầy đủ mà Hermes tải khi kỹ năng này được kích hoạt. Đây là những gì tác nhân coi là hướng dẫn khi kỹ năng được kích hoạt.

QMD - Tài liệu đánh dấu truy vấn

Công cụ tìm kiếm cục bộ trên thiết bị cho cơ sở kiến thức cá nhân. Đánh dấu chỉ mục ghi chú, bản ghi cuộc họp, tài liệu và bất kỳ tệp văn bản nào, sau đó cung cấp tìm kiếm kết hợp kết hợp từ khóa, hiểu ngữ nghĩa và Xếp hạng lại được hỗ trợ bởi LLM - tất cả đều chạy cục bộ mà không phụ thuộc vào đám mây.

Được tạo bởi Tobi Lütke. MIT được cấp phép.

Khi nào nên sử dụng

Người dùng yêu cầu tìm kiếm ghi chú, tài liệu, cơ sở kiến thức hoặc bản ghi cuộc họp của họ
Người dùng muốn tìm thứ gì đó trong một bộ sưu tập lớn các tệp văn bản/đánh dấu
Người dùng muốn tìm kiếm ngữ nghĩa ("tìm ghi chú về khái niệm X") không chỉ từ khóa grep
Người dùng đã thiết lập bộ sưu tập qmd và muốn truy vấn chúng
Người dùng yêu cầu thiết lập cơ sở tri thức địa phương hoặc hệ thống tìm kiếm tài liệu
Từ khóa: "tìm kiếm ghi chú của tôi", "tìm trong tài liệu của tôi", "cơ sở kiến thức", "qmd"

Điều kiện tiên quyết

Node.js >= 22 (bắt buộc)

# Check version
node --version  # must be >= 22

# macOS — install or upgrade via Homebrew
brew install node@22

# Linux — use NodeSource or nvm
curl -fSSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs
# or with nvm:
nvm install 22 && nvm use 22

`

### SQLite có hỗ trợ mở rộng (chỉ macOS)

hệ thống macOS SQLite thiếu tải tiện ích mở rộng. Cài đặt qua Homebrew:

``` bash
brew install SQLite

`

### Cài đặt qmd

`bash
npm install -g @tobilu/qmd

# or with Bun:
bun install -g @tobilu/qmd

`
``Lần chạy đầu tiên tự động tải xuống 3 mô hình GGUF cục bộ (tổng cộng ~ 2GB):

| Người mẫu | Mục đích | Kích thước |
|-------|----------|------|
| nhúnggemma-300M-Q8_0 | nhúng vector | ~300MB |
| qwen3-reranker-0.6b-q8_0 | Xếp hạng lại kết quả | ~640MB |
| qmd-truy vấn-mở rộng-1.7B | Mở rộng truy vấn | ~1,1GB |

### Xác minh cài đặt

``` bash
qmd --version
qmd status

`

## Tham khảo nhanh

| Lệnh | Nó làm gì | Tốc độ |
|----------|-------------|-------|
| 
`qmd search "query"
` | Tìm kiếm từ khóa BM25 (không có mẫu) | ~0,2 giây |
| 
`qmd vsearch "query"
` | Tìm kiếm vectơ ngữ nghĩa (1 mô hình) | ~3 giây |
| 
`qmd query "query"
` | Kết hợp + sắp xếp lại (cả 3 mô hình) | ~2-3 giây ấm, ~19 giây lạnh |
| 
`qmd get &lt;docid
` | Truy xuất toàn bộ nội dung tài liệu | ngay lập tức |
| 
`qmd multi-get "glob"
` | Truy xuất nhiều tệp | ngay lập tức |
| 
`qmd collection add &lt;path --name &lt;n
` | Thêm một thư mục dưới dạng bộ sưu tập | ngay lập tức |
| 
`qmd context add &lt;path "description"
` | Thêm siêu dữ liệu ngữ cảnh để cải thiện khả năng truy xuất | ngay lập tức |
| 
`qmd embed
` | Tạo/cập nhật các phần nhúng vector | khác nhau |
| 
`qmd status
` | Hiển thị thông tin về tình trạng chỉ mục và bộ sưu tập | ngay lập tức |
| 
`qmd MCP
` | Khởi động máy chủ MCP (stdio) | kiên trì |
| 
`qmd MCP --http --daemon
` | Khởi động máy chủ MCP (HTTP, kiểu máy ấm) | kiên trì |

## Quy trình thiết lập

### 1. Thêm bộ sưu tập

Trỏ qmd vào các thư mục chứa tài liệu của bạn:

`bash

# Add a notes directory
qmd collection add ~/notes --name notes

# Add project docs
qmd collection add ~/projects/myproject/docs --name project-docs

# Add meeting transcripts
qmd collection add ~/meetings --name meetings

# List all collections
qmd collection list

`

### 2. Thêm mô tả ngữ cảnh

Siêu dữ liệu ngữ cảnh giúp công cụ tìm kiếm hiểu từng bộ sưu tập là gì
chứa đựng. Điều này cải thiện đáng kể chất lượng truy xuất:

``` bash
qmd context add qmd://notes "Personal notes, ideas, and journal entries"
qmd context add qmd://project-docs "Technical documentation for the main project"
qmd context add qmd://meetings "Meeting transcripts and action items from team syncs"

`

### 3. Tạo phần nhúng

`bash
qmd embed

`
``Điều này xử lý tất cả các tài liệu trong tất cả các bộ sưu tập và tạo ra vector
nhúng. Chạy lại sau khi thêm tài liệu hoặc bộ sưu tập mới.

### 4. Xác minh

`bash
qmd status   # shows index health, collection stats, model info

`

## Mẫu tìm kiếm

### Tìm kiếm từ khóa nhanh (BM25)

Tốt nhất cho: thuật ngữ chính xác, mã định danh, tên, cụm từ đã biết.
Không có mô hình nào được tải - kết quả gần như ngay lập tức.

`bash
qmd search "authentication middleware"
qmd search "handleError async"

`

### Tìm kiếm theo vectơ ngữ nghĩa

Tốt nhất cho: câu hỏi ngôn ngữ tự nhiên, truy vấn khái niệm.
Tải mô hình nhúng (~3 giây truy vấn đầu tiên).

`bash
qmd vsearch "how does the rate limiter handle burst traffic"
qmd vsearch "ideas for improving onboarding flow"

`

### Tìm kiếm kết hợp với sắp xếp lại (Chất lượng tốt nhất)

Tốt nhất cho: các truy vấn quan trọng trong đó chất lượng là quan trọng nhất.
Sử dụng cả 3 mô hình - mở rộng truy vấn, vectơ BM25+ song song, sắp xếp lại.

`bash
qmd query "what decisions were made about the database migration"

`

### Truy vấn có cấu trúc đa chế độKết hợp các loại tìm kiếm khác nhau trong một truy vấn duy nhất để đảm bảo độ chính xác:

`bash

# BM25 for exact term + vector for concept
qmd query $'lex: rate limiter\nvec: how does throttling work under load'

# With query expansion
qmd query $'expand: database migration plan\nlex: "schema change"'

`

### Cú pháp truy vấn (chế độ lex/BM25)

| Cú pháp | Hiệu ứng | Ví dụ |
|--------|--------|---------|
| 
`term
` | Trận đấu tiền tố |

perf
` phù hợp với "hiệu suất" |
| 

"phrase"
` | Cụm từ chính xác |

"rate limiter"
` |
| 

-term
` | Loại trừ thuật ngữ |

performance -sports
` |

### HyDE (Nhúng tài liệu giả định)

Đối với các chủ đề phức tạp, hãy viết những gì bạn mong đợi câu trả lời như sau:

``` bash
qmd query $'hyde: The migration plan involves three phases. First, we add the new columns without dropping the old ones. Then we backfill data. Finally we cut over and remove legacy columns.'

`

### Phạm vi cho Bộ sưu tập

`bash
qmd search "query" --collection notes
qmd query "query" --collection project-docs

`

### Định dạng đầu ra

`bash
qmd search "query" --JSON        # JSON output (best for parsing)
qmd search "query" --limit 5     # Limit results
qmd get "#abc123"                # Get by document ID
qmd get "path/to/file.md"       # Get by file path
qmd get "file.md:50" -l 100     # Get specific line range
qmd multi-get "journals/*.md" --JSON  # Batch retrieve by glob

`

## Tích hợp MCP (Được khuyến nghị)

qmd hiển thị máy chủ MCP cung cấp công cụ tìm kiếm trực tiếp cho
Đại lý Hermes thông qua ứng dụng khách MCP gốc. Đây là ưu tiên
tích hợp - sau khi được định cấu hình, tác nhân sẽ tự động nhận các công cụ qmd
mà không cần phải tải kỹ năng này.

### Tùy chọn A: Chế độ Stdio (Đơn giản)

Thêm vào 

~/.Hermes/config.yaml

:

`YAML
MCP_servers:
  qmd:
    command: "qmd"
    args: ["MCP"]
    timeout: 30
    connect_timeout: 45

`
``Công cụ này đăng ký: 
`MCP_qmd_search

, 
`MCP_qmd_vsearch

,
`MCP_qmd_deep_search

, 
`MCP_qmd_get

, 
`MCP_qmd_status

.

**Sự cân bằng:** Tải mô hình trong cuộc gọi tìm kiếm đầu tiên (bắt đầu nguội khoảng 19 giây),
sau đó giữ ấm cho buổi tập. Chấp nhận được để sử dụng thường xuyên.

### Tùy chọn B: Chế độ HTTP Daemon (Nhanh, Được khuyến nghị khi sử dụng nhiều)

Khởi động daemon qmd một cách riêng biệt - nó giữ cho các mô hình luôn ấm trong bộ nhớ:

`bash

# Start daemon (persists across agent restarts)
qmd MCP --http --daemon

# Runs on http://localhost:8181 by default

`
``Sau đó định cấu hình Hermes Agent để kết nối qua HTTP:

``` yaml
MCP_servers:
  qmd:
    url: "http://localhost:8181/MCP"
    timeout: 30

`
``**Đánh đổi:** Sử dụng ~2GB RAM khi chạy, nhưng mọi truy vấn đều nhanh
(~2-3 giây). Tốt nhất cho người dùng tìm kiếm thường xuyên.

### Giữ Daemon chạy

#### macOS (launchd)

`bash
cat > ~/Library/LaunchAgents/com.qmd.daemon.plist &lt;&lt; 'EOF'
&lt;?xml version="1.0" encoding="UTF-8"?>
&lt;!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.Apple.com/DTDs/PropertyList-1.0.dtd">
&lt;plist version="1.0"
&lt;dict
  &lt;keyLabel&lt;/key
  &lt;stringcom.qmd.daemon&lt;/string
  &lt;keyProgramArguments&lt;/key
  &lt;array
    &lt;stringqmd&lt;/string
    &lt;stringMCP&lt;/string
    &lt;string--http&lt;/string
    &lt;string--daemon&lt;/string
  &lt;/array
  &lt;keyRunAtLoad&lt;/key
  &lt;true/
  &lt;keyKeepAlive&lt;/key
  &lt;true/
  &lt;keyStandardOutPath&lt;/key
  &lt;string/tmp/qmd-daemon.log&lt;/string
  &lt;keyStandardErrorPath&lt;/key
  &lt;string/tmp/qmd-daemon.log&lt;/string
&lt;/dict
&lt;/plist
EOF`launchctl load ~/Library/LaunchAgents/com.qmd.daemon.plist

`

#### Linux (dịch vụ người dùng systemd)

`bash
mkdir -p ~/.config/systemd/user`cat > ~/.config/systemd/user/qmd-daemon.service &lt;&lt; 'EOF'
[Unit]
Description=QMD MCP Daemon
After=network.target`[Service]
ExecStart=qmd MCP --http --daemon
Restart=on-failure
RestartSec=10
Environment=PATH=/usr/local/bin:/usr/bin:/bin`[Install]
WantedBy=default.target
EOF`systemctl --user daemon-reload
systemctl --user enable --now qmd-daemon
systemctl --user status qmd-daemon

`

### Tham khảo công cụ MCP

Sau khi được kết nối, các công cụ này sẽ có sẵn dưới dạng 
`MCP_qmd_*

:

| Công cụ MCP | Bản đồ tới | Mô tả |
|----------|----------|-------------|
| 
`MCP_qmd_search
` | 
`qmd search
` | Tìm kiếm từ khóa BM25 |
| 
`MCP_qmd_vsearch
` | 
`qmd vsearch
` | Tìm kiếm vectơ ngữ nghĩa |
| 
`MCP_qmd_deep_search
` | 
`qmd query
` | Tìm kiếm kết hợp + sắp xếp lại |
| 
`MCP_qmd_get
` | 
`qmd get
` | Truy xuất tài liệu theo ID hoặc đường dẫn |
| 
`MCP_qmd_status
` | 
`qmd status
` | Chỉ số sức khỏe và số liệu thống kê |

Các công cụ MCP chấp nhận các truy vấn JSON có cấu trúc để tìm kiếm nhiều chế độ:

`JSON
&#123;
  "searches": [
    \&#123;"type": "lex", "query": "authentication middleware"&#125;,
    \&#123;"type": "vec", "query": "how user login is verified"&#125;
  ],
  "collections": ["project-docs"],
  "limit": 10
&#125;

`

## Cách sử dụng CLI (Không có MCP)

Khi MCP không được định cấu hình, hãy sử dụng qmd trực tiếp qua terminal:

`
terminal(command="qmd query 'what was decided about the API redesign' --JSON", timeout=30)

`
``Đối với các tác vụ thiết lập và quản lý, hãy luôn sử dụng terminal:

`
terminal(command="qmd collection add ~/Documents/notes --name notes")
terminal(command="qmd context add qmd://notes 'Personal research notes and ideas'")
terminal(command="qmd embed")
terminal(command="qmd status")

`

## Cách thức hoạt động của Đường ống tìm kiếm

Hiểu rõ nội bộ giúp chọn chế độ tìm kiếm phù hợp:
1. **Mở rộng truy vấn** — Mô hình 1.7B được tinh chỉnh tạo ra 2 lựa chọn thay thế
   truy vấn. Bản gốc có trọng lượng gấp đôi khi kết hợp.

2. **Truy xuất song song** — BM25 (SQLite FTS5) và chạy tìm kiếm vectơ
   đồng thời trên tất cả các biến thể truy vấn.
3. **RRF Fusion** — Kết hợp xếp hạng đối ứng (k=60) hợp nhất các kết quả.
   Phần thưởng xếp hạng cao nhất: #1 được +0,05, #2-3 nhận được +0,02.
4. **Xếp hạng lại LLM** — qwen3-reranker chấm điểm 30 ứng viên hàng đầu (0,0-1,0).
5. **Kết hợp nhận biết vị trí** — Xếp hạng 1-3: 75% truy xuất / 25% xếp hạng lại.
   Hạng 4-10: 60/40. Xếp hạng 11+: 40/60 (tin tưởng người xếp hạng lại nhiều hơn cho đuôi dài).

**Phân đoạn thông minh:** Tài liệu được phân chia theo các điểm ngắt tự nhiên (tiêu đề,
khối mã, dòng trống) nhắm mục tiêu ~ 900 mã thông báo với tỷ lệ trùng lặp 15%. Mã
khối không bao giờ được chia giữa khối.

## Các phương pháp hay nhất
1. **Luôn thêm mô tả ngữ cảnh** — 
`qmd context add
` một cách đáng kể
   cải thiện độ chính xác truy xuất. Mô tả những gì mỗi bộ sưu tập chứa.
2. **Nhúng lại sau khi thêm tài liệu** — 
`qmd embed
` phải được chạy lại khi
   các tập tin mới được thêm vào bộ sưu tập.
3. **Sử dụng 
`qmd search
` để tăng tốc** — khi bạn cần tra cứu từ khóa nhanh chóng
   (mã nhận dạng, tên chính xác), BM25 hoạt động ngay lập tức và không cần mô hình.
4. **Sử dụng 
`qmd query
` để biết chất lượng** — khi câu hỏi mang tính khái niệm hoặc
   người dùng cần kết quả tốt nhất có thể, hãy sử dụng tìm kiếm kết hợp.
5. **Ưu tiên tích hợp MCP** — sau khi được định cấu hình, tác nhân sẽ trở thành tác nhân gốc
   công cụ mà không cần phải tải kỹ năng này mỗi lần.
6. **Chế độ daemon dành cho người dùng thường xuyên** — nếu người dùng tìm kiếm
   cơ sở kiến thức thường xuyên, khuyên bạn nên thiết lập daemon HTTP.
7. **Truy vấn đầu tiên trong tìm kiếm có cấu trúc có trọng lượng gấp 2 lần** — đặt nhiều nhất
   truy vấn quan trọng/nhất định trước tiên khi kết hợp lex và vec.

## Khắc phục sự cố### "Tải mô hình ở lần chạy đầu tiên"
Bình thường — qmd tự động tải xuống ~2GB mô hình GGUF trong lần sử dụng đầu tiên.
Đây là một hoạt động một lần.

### Độ trễ khởi động nguội (~19 giây)
Điều này xảy ra khi mô hình không được tải vào bộ nhớ. Giải pháp:
- Sử dụng chế độ daemon HTTP (
`qmd MCP --http --daemon

) để giữ ấm
- Sử dụng 
`qmd search
` (chỉ BM25) khi không cần mẫu máy
- Chế độ MCP stdio tải các mô hình trong lần tìm kiếm đầu tiên, giữ ấm cho phiên

### macOS: "không thể tải tiện ích mở rộng"
Cài đặt Homebrew SQLite: 
`brew install SQLite

Sau đó đảm bảo nó ở trên PATH trước SQLite hệ thống.

### "Không tìm thấy bộ sưu tập nào"
Chạy 
`qmd collection add &lt;path --name &lt;name
` để thêm thư mục,
sau đó 
`qmd embed
` để lập chỉ mục cho chúng.

### Ghi đè mô hình nhúng (CJK/đa ngôn ngữ)
Đặt biến môi trường 
`QMD_EMBED_MODEL
` cho nội dung không phải tiếng Anh:

`
``` bash
 export QMD_EMBED_MODEL="your-multilingual-model"

`

## Lưu trữ dữ liệu
- **Chỉ mục & vectơ:** 

~/.cache/qmd/index.SQLite

`
- **Mô hình:** Tự động tải xuống bộ đệm cục bộ trong lần chạy đầu tiên
- **Không phụ thuộc vào đám mây** — mọi thứ đều chạy cục bộ

## Tài liệu tham khảo
- [GitHub: tobi/qmd](https://GitHub.com/tobi/qmd)
- [QMD Changelog](https://GitHub.com/tobi/qmd/blob/main/CHANGELOG.md)

Siêu dữ liệu kỹ năng​

Tham khảo: đầy đủ SKILL.md​

QMD - Tài liệu đánh dấu truy vấn

Khi nào nên sử dụng​

Điều kiện tiên quyết​

Node.js >= 22 (bắt buộc)​

Siêu dữ liệu kỹ năng

Tham khảo: đầy đủ SKILL.md

Khi nào nên sử dụng

Điều kiện tiên quyết

Node.js >= 22 (bắt buộc)