线上 Rust LanceDB 报错问题处理~

![](https://blog.42tr.cn/static/img/f208dec396b94e50cd6c283eeb3a6ced.0249f7d955002a045e0e1503995afb5f.jpg)



报错内容：
```log
thread '<unnamed>' (245) panicked at library/std/src/sys/pal/unix/stack_overflow.rs:231:13:
failed to set up alternative stack guard page: Cannot allocate memory (os error 12)
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

thread '<unnamed>' (246) panicked at library/std/src/sys/pal/unix/stack_overflow.rs:231:13:
failed to set up alternative stack guard page: Cannot allocate memory (os error 12)
2026-03-19 15:07:33 [lance_io::local] DEBUG - get_range: range=713265..717361

thread '<unnamed>' (247) panicked at library/std/src/sys/pal/unix/stack_overflow.rs:227:13:
failed to allocate an alternative stack: Cannot allocate memory (os error 12)
2026-03-19 15:07:33 [lance_io::local] DEBUG - open; path=Path { raw: "app/data/lancedb_data/documents.lance/data/3836854-10fc-49da-af99-3315c0982ed4.lance" } block-size=4096 know.
fatal runtime error: failed to initiate panic, error fatal runtime error: failed to initiate panic, error fatal runtime error: failed to initiate panic, error 555, aborting
, aborting
, aborting
memory allocation of 41 bytes failed
```
### 猜测一：RAM 不足
从报错可以看到是内存分配失败，启动时监控内存 `free -mh`，内存变化不大，确认不是 RAM 不足。

### 猜测二：Docker 容器限制
猜测是 Docker 容器限制了内存使用，修改 `docker-compose.yaml`
```yaml
services:
  app:
    image: your-image
    mem_limit: 128g
```
发现还是不行。

### 猜测三：虚拟内存不足

![image.png](/static/img/4e1af38d3ebaf1bdb0206df4cb9f2fee.image.png)
根据AI推理，修改 stack 大小
```yaml
services:
  app:
    ulimits:
      stack: 1024
```
仍然不行。

尝试增加 swap，依然不行。

### 猜测四：mmap（实际问题）
因为 lancedb 会把数据读到 mmap 提高访问速度

查询系统允许的最大 mmap 数量
```shell
> cat /proc/sys/vm/max_map_count
262162 /proc/2440330/maps
```

查询 mmap 数量
```shell
pid=$(pgrep -f '/app/htknow|htknow' | head -n1)
wc -l /proc/$pid/maps
```

临时修改
```shell
sysctl -w vm.max_map_count=1048576
```
再启动就 ok 了，确认是该问题。

持久化配置
```shell
echo 'vm.max_map_count=2097152' | sudo tee /etc/sysctl.d/99-htknow.conf
sudo sysctl --system
```

Rust LanceDB 内存不足问题

![image.png](/static/img/c7acc431b3ce8354959da1a6bdf295c6.image.png)



克鲁斯卡尔算法（Kruskal Algorithm）是一种用于求解最小生成树（Minimum Spanning Tree, MST）的经典贪心算法，适用于无向加权图。

**核心思想**：每次选择当前权重最小、且不会形成环的边加入生成树。

**关键点**：使用并查集判断是否会形成环。

**时间复杂度**
- 排序边：O(E log E)
- 并查集操作：近似 O(E α(N))（α 是反阿克曼函数，极小）

总体复杂度：O(E log E)

代码：
```python
def kruskal(n: list, edges: list[list[int]]): # [[端点1, 端点2, 权重], ...]
    edges.sort(key=lambda x: x[2])  # 按权重排序
    dsu = DSU(n)
    mst = []
    
    for u, v, w in edges:
        if dsu.find(u) == dsu.find(v):
            continue
        dsu.union(u, v)
        mst.append((u, v, w))
  
    return mst
```

练习题：[3600.升级后最大生成树稳定性](https://leetcode.cn/problems/maximize-spanning-tree-stability-with-upgrades/description/)

最小生成树克鲁斯卡尔（Kruskal）算法

**并查集（Union Find / Disjoint Set Union）** 是一种用于管理分组的数据结构（一般使用树形结构来表示）~





（1）Find：查询 a 元素和 b 元素是否为同一组（只需要判断他们的 root 根节点是否为同一个即可）

（2）Union：合并元素 a 和 b 为同一组


代码

```python
class DSU:
    def __init__(self, parent: list[int]):
        this.parent = parent
        
    def find(self, x: int):
        if self.parent[x] != x:
            self.parent[x] = self.find(self.parent[x])
        return self.parent[x]
        
    def union(self, x: int, y: int):
        px = self.find(x)
        py = self.find(y)
        self.parent[px] = py
```

并查集

![image.png](/static/img/498183653de6f0b2db1fb4da88fc0bf3.image.png)




PageIndex 的核心目标是解决一个问题：
> 如何让 LLM 高质量理解长文档，并实现精准搜索。

传统 RAG 的问题：

- 文档 chunk 切得很碎
- 结构信息丢失
- 搜索结果上下文不完整
- LLM 容易产生幻觉

PageIndex 的思路是：
> 先理解文档结构 → 再建立树状索引 → 再做向量搜索

而不是直接 chunk。

整个系统可以拆成两个阶段：

**离线阶段（Indexing）**

`文档解析 → 结构提取 → 索引构建 → 向量存储`

**在线阶段（Query）**

`用户问题 → 向量搜索 → 结构补全 → LLM回答`

## 一、文档解析流程（Document Parsing）

文档解析的目标是：

> 把 PDF / Word / Markdown 转换成可理解的结构化数据

典型输入：
- PDF
- Word
- Markdown
- HTML

解析流程如下。

### 1 文档加载

首先系统加载原始文档。

核心任务：
- 读取文档
- 转换为文本
- 保留基础结构

可能用到的工具：
- pdf parser
- docx parser
- html parser

输出类似：
```json
{
  "pages": [
    {
      "text": "...",
      "layout": "..."
    }
  ]
}
```
此时仍然是原始文本。

### 2 文档结构解析

接下来需要识别文档结构。

系统会识别：
- 标题（H1 / H2 / H3）
- 段落
- 列表
- 表格
- 代码块

**例如：**

原文：
```markdown
1. Introduction
This paper introduces...
2. Method
```

会被解析成：
```json
[
  { "type": "heading", "level": 1, "text": "Introduction" },
  { "type": "paragraph", "text": "This paper introduces..." },
  { "type": "heading", "level": 1, "text": "Method" }
]
```
这一步的意义是：
> 恢复文档逻辑结构。

### 3 LLM 推理生成初始目录

如果文档结构不明显（很多 PDF 都这样），系统会调用 LLM。

让 LLM：

> 根据文本推断文档目录结构

例如：

输入：
```txt
大量文本
```
输出：
```txt
1 Introduction
2 Background
3 Method
4 Experiment
```
这一步得到：

> Document Outline

也就是 **初始目录线索**。

### 4 构建文档树（Document Tree）

有了标题信息之后，就可以生成 文档树结构。

例如：
```txt
Document
 ├── Introduction
 │     ├── paragraph
 │     └── paragraph
 │
 ├── Method
 │     ├── subsection
 │     └── subsection
 │
 └── Experiment
```
内部结构通常是：
```
Node {
    title
    level
    content
    children
}
```

这样每一段文本都有：
- 父节点
- 子节点
- 层级关系

这就是 PageIndex 的核心结构。

### 5 文档 Chunk 切分

接下来系统会生成检索单元。

但和传统 RAG 不同：

> 不是固定长度切分

而是：

> 按结构切分

例如：
```
Section
Subsection
Paragraph
```
形成 chunk：
```
chunk_1 = "Introduction section"
chunk_2 = "Method subsection"
chunk_3 = "Experiment subsection"
```
同时保留：
```
parent
section path
```
例如：
```
path = Introduction > Background
```
这对于搜索非常重要。

### 6 Embedding 向量化

然后系统会对每个 chunk 生成向量存入向量库

### 7 构建索引

最终索引包含：
- text
- embedding
- tree path
- node id
- parent id

例如：
```json
{
  "text": "...",
  "vector": [...],
  "path": "Method > Architecture",
  "node_id": 123
}
```
到这里 **离线阶段完成**。


## 二、搜索流程（Query Pipeline）

当用户提问时，系统开始在线搜索流程。

### 1 Query 解析

用户输入：
```
How does the method work?
```
系统会：
- 清洗 query
- 生成 embedding

得到：
```
query vector
```

### 2 向量搜索

在向量数据库中查找 TopK 相似 chunk

返回：
```
Method section
Architecture subsection
Algorithm description
```
这是 第一层召回。

### 3 结构补全

如果只返回 chunk，LLM 很可能缺上下文。

所以 PageIndex 会：
- 补充父节点
- 补充兄弟节点
- 补充上下文

例如：

原始 chunk：
```
Algorithm Step 2
```
系统会扩展为：
```
Method
 └ Algorithm
      ├ Step1
      ├ Step2
      └ Step3
```
这样上下文完整。

### 4 上下文重排序

如果 chunk 很多，需要排序。

排序依据：
- embedding 相似度
- 文档结构距离
- LLM rerank

最终选择：`Top N context`

### 5 构造 LLM Prompt

系统构造 Prompt：
```
Context:
[document chunks]

Question:
user query
```
例如：
```
Answer based on the following document.
```

### 6 LLM 生成答案

最后调用 LLM 输出：

final answer

同时可能附带：
- 引用来源
- section path

例如：
```
Source: Method > Architecture
```

## 三、核心算法
### 1. 文档树生成算法
核心思想：
> 把文档转换成类似 HTML DOM 的树结构

结构示意：
```txt
Document
 ├── Section
 │     ├── Subsection
 │     │       ├── Paragraph
 │     │       └── Paragraph
 │     └── Subsection
 └── Section
```
每个节点都保存：
```txt
Node
 ├ id
 ├ title
 ├ content
 ├ level
 ├ parent
 └ children
```
构建流程通常是 三阶段。

#### 1 结构元素检测

首先解析文本块类型：
- heading
- paragraph
- list
- table
- code

例如：
```txt
1 Introduction
This paper proposes...
```
解析结果：
```txt
Heading(level=1)
Paragraph
```
在 PDF 场景下，通常还会利用：
- 字体大小
- 字体粗细
- 行距
- 版面布局

来识别标题。

例如：
```
FontSize > 18 → H1
FontSize > 14 → H2
```
这样可以初步恢复文档结构。

#### 2 层级推断

如果文档本身没有明确层级（很多 PDF 都是这样），就需要推断。

典型方法：

**方法1：规则推断**

例如：
```txt
1
1.1
1.1.1
```
直接转换成：
```
level1
level2
level3
```
**方法2：LLM 推断**

当结构不清晰时，让 LLM 推理：

输入：
```
大量文本片段
```
输出：
```
Possible outline:
1 Introduction
2 Background
3 Method
```
但注意：

> 不会把整个文档给 LLM。

而是：

> 抽样片段 + 标题候选

这样 token 很小。

#### 3 树结构构建

当拿到标题层级之后，构建树结构。

伪代码：
```
stack = []

for element in elements:
    if element is heading:
        while stack.top.level >= element.level:
            stack.pop()

        stack.top.children.append(element)
        stack.push(element)

    else:
        stack.top.children.append(element)
```
最终得到：
```
Document Tree
```
优势：
- 结构清晰
- 支持父子检索
- 支持上下文扩展


### 搜索时的结构扩展策略

普通 RAG 的最大问题：

> chunk 太碎

例如：
```txt
Algorithm Step 2
```
LLM 根本不知道：
```
Step1
Step3
```
PageIndex 的解决办法是：

> 结构扩展（Structure Expansion）

流程如下。

**1 初始向量召回**

首先正常向量搜索：
```
query embedding
↓
vector search
↓
topK chunks
```
例如：
```
Chunk A
Chunk B
Chunk C
```
但这些 chunk 只是局部。

**2 向上扩展（Parent Expansion）**

系统会找：

> 父节点

例如：

原始结果：
```
Algorithm Step 2
```
扩展后：
```
Method
 └ Algorithm
      └ Step 2
```
这样 LLM 就知道：

> 这是 Method 章节里的算法

**3 向下扩展（Child Expansion）**

如果 chunk 是一个标题节点：
```
Algorithm
```
系统会补充：
```
Algorithm
 ├ Step1
 ├ Step2
 └ Step3
```
这样内容更完整。

**4 兄弟节点扩展（Sibling Expansion）**

有时需要增加相邻信息：
```
Step1
Step2
Step3
```
而不是只给：
```
Step2
```
这样能明显提高回答质量。

**5 Token Budget 控制**

扩展不是无限的。

系统会控制：

> max_tokens

例如：

> 4000 tokens context

策略：
- 优先保留最相关 chunk
- 逐层扩展
- 直到 token 满

类似：
```
relevance-first expansion
```

### LLM 生成目录为什么不会超上下文

很多人看到 PageIndex 的一个步骤：

> LLM 推理生成文档目录

会有疑问：

> 文档几百页，LLM 怎么可能读完？

实际上它用了 分层策略。

**1 文档分段**

首先文档会被切成块：

> chunk size ≈ 500 tokens

例如：
```
chunk1
chunk2
chunk3
...
```
每个 chunk 单独分析。

**2 局部目录生成**

LLM 对每一小段生成：

> local outline

例如：
```
chunk1 → Introduction
chunk2 → Method
chunk3 → Experiment
```

**3 Outline 合并**

系统再把这些 outline 合并：

> merge outlines

类似：

> map-reduce

过程：
```
local outline
     ↓
merge
     ↓
global outline
```

**4 层级压缩**

如果目录太长，还会压缩：

例如：

原始：
```
1 Introduction
1.1 Motivation
1.2 Background
2 Method
2.1 Architecture
2.2 Training
```
压缩为：
```
Introduction
Method
Experiment
```
这样 token 极小

PageIndex架构分析

![](https://blog.42tr.cn/static/img/091832ca46397412018e0f979e75b806.image.png)



## 环境准备
需要 jeprof 工具解析 heap 文件 `apt install libjemalloc-dev graphviz`

## 代码
cargo.toml
```toml
[package]
name = "test260202"
version = "0.1.0"
edition = "2024"

[dependencies]
tikv-jemallocator = { version = "0.6", features = ["profiling"] }
tikv-jemalloc-ctl = { version = "0.6", features = ["profiling", "use_std"] }
```

main.rs
```rust
#[global_allocator]
static GLOBAL: tikv_jemallocator::Jemalloc = tikv_jemallocator::Jemalloc;

#[unsafe(export_name = "_rjem_malloc_conf")]
// lg_prof_sample:0 表示每次分配都采样(最详细,但性能开销大)
// lg_prof_sample:10 表示每 1KB 采样一次(推荐)
// lg_prof_sample:19 表示每 512KB 采样一次(默认值)
pub static MALLOC_CONF: &[u8] = b"prof:true,prof_active:true,lg_prof_sample:10\0";

use std::{
    ffi::CString,
    fs,
    process::Command,
    time::{Duration, SystemTime, UNIX_EPOCH},
};

use tikv_jemalloc_ctl::raw;
fn main() {
    let mut keep = Vec::new();
    for _ in 0..1024 {
        keep.push(vec![0u8; 4096]);
    }
    std::thread::sleep(Duration::from_millis(200));

    let path = heap_profile_pdf_impl();
    println!("Heap profile PDF saved to {}", path.display());
    std::mem::forget(keep);
}

fn heap_profile_pdf_impl() -> std::path::PathBuf {
    let pid = std::process::id();
    let ts = SystemTime::now()
        .duration_since(UNIX_EPOCH)
        .expect("SystemTime error")
        .as_secs();

    // 生成 heap dump 文件
    let heap_filename = format!("heap.{}.{}.heap", pid, ts);
    let mut heap_path = std::env::temp_dir();
    heap_path.push(&heap_filename);
    let heap_path_str = heap_path.to_string_lossy().into_owned();
    let c_path =
        CString::new(heap_path_str.clone()).expect("Failed to create C string for heap path");

    // 导出 heap dump
    println!("Generating heap dump: {}", heap_path_str);
    let ptr = c_path.as_ptr();
    unsafe {
        raw::write(b"prof.dump\0", ptr).expect("jemalloc heap dump failed");
    }

    // 生成 PDF 文件
    let pdf_filename = format!("heap.{}.{}.pdf", pid, ts);
    let mut pdf_path = std::env::current_dir().expect("Failed to get current dir");
    pdf_path.push(&pdf_filename);
    let pdf_path_str = pdf_path.to_string_lossy().into_owned();

    // 获取当前二进制文件路径
    let binary_path = std::env::current_exe().expect("Failed to get binary path");
    let binary_path_str = binary_path.to_string_lossy();

    println!(
        "Running jeprof: binary={}, heap={}, output={}",
        binary_path_str, heap_path_str, pdf_path_str
    );

    // 执行 jeprof 命令
    let output = Command::new("jeprof")
        .arg("--pdf")
        .arg(binary_path_str.as_ref())
        .arg(&heap_path_str)
        .output()
        .expect("Failed to execute jeprof (make sure jeprof is installed)");

    if !output.status.success() {
        let stderr = String::from_utf8_lossy(&output.stderr);
        let _ = fs::remove_file(&heap_path);
        panic!("jeprof execution failed: {}", stderr);
    }

    // 读取生成的 PDF
    let pdf_bytes = output.stdout;
    if pdf_bytes.is_empty() {
        let _ = fs::remove_file(&heap_path);
        panic!("jeprof generated empty PDF");
    }

    fs::write(&pdf_path, &pdf_bytes).expect("Failed to write PDF");

    // 清理临时文件
    let _ = fs::remove_file(&heap_path);

    println!(
        "Successfully generated heap profile PDF: {} bytes",
        pdf_bytes.len()
    );

    pdf_path
}
```

## 使用
`cargo run` 在当前目录生成文件 `heap.3742391.1770170243.pdf`，可以加到 debug 中实时生成 heap 文件，pdf 文件可后续有问题时再解析，也可以使用其他方式处理 heap 文件。