一、背景

RAG是让大模型回答私有/长尾知识的主流方案：先把文档切成块向量化。收到问题时检索相关片段，连同问题一起交给 LLM 生成带引用的回答。

使用者痛点：

• 市面上多数实现依赖 LangChain、LlamaIndex 等重量级框架，部署成本高、难以定制。
• 答案缺乏可追溯性，模型往往“凭空”编造内容。
• 向量数据库收费或自行搭建复杂，对小规模私有数据来说成本不划算。
• 检索准确率低，导致生成答案与真实文档不匹配。

本项目的主要原因全部从零手写不依赖上述框架，把 RAG 的每个环节亲手搭一遍。

语料是数篇原创的 iOS 开发知识笔记，RAG 的目标就是让模型能回答这些私有知识。

二、程序总览

flowchart LR
subgraph 离线索引
A --> B
B --> C
C --> D
end
subgraph 在线问答
Q --> E
E --> F
F --> G
G --> H
end
D -. 相似度计算 .-> F

程序分为离线索引和在线问答两条流水线。下面分别说明每个环节的作用与原理。

离线索引

• chunk 切块把整篇文档拆成独立的小片段，每个片段单独向量化。这样检索时能精确命中某一段内容。说起来，痛点解决：避免长文本整体向量导致语义稀释和超出 embedding 模型长度限制。其实，
• embed 向量化embedding 模型把每个 chunk 编码成一个向量——语义相近的文本向量在空间中靠近、无关的远离。为后续相似度计算提供依据。
• 存进矩阵所有向量拼成一个 N 行 × D 列的 numpy 矩阵，即“可检索的索引”。痛点解决：无需额外向量数据库，实现低成本、本地化存储。

在线问答

• 问题向量化: 使用同一 embedding 模型把使用者的问题编码成向量，确保在同一语义空间里比较一下。
• retrieve 检索: 计算问题向量与矩阵中每行的相似度，找出最相关的 top‑k 块。这一步决定了 LLM 能否看到正确内容。痛点解决：Simplify retrieval logic to milliseconds for thousands of chunks。avoiding latency of remote services.
• answer 生成: 将检索到的块编号塞进 prompt，连同问题一起交给 LLM，并要求使用 标注依据，实现**答案可追溯**。

三、环境配置与技术栈

开发环境：

• + Python。

技术选型 & 参数：

Libraries：

• : 调用 DeepSeek API
• : 向量矩阵存储 & 余弦相似度计算
• : 加载 BGE 模型进行向量化
• : HuggingFace 模型加载库。被 sentence‑transformers 依赖
• : 深度学习框架，用于 BGE 前向推理
• : 从 .env 读取 API Key，避免硬编码

四、chunk：切块的艺术

The first design decision in any RAG pipeline is how to split documents into manageable pieces.

flowchart TD
A --> B
B --> C
C --> D{单行超过上限?}
D -->|是| E
D -->|否| F
E --> G
F --> G
G --> H

The design focuses on two key pain points:


*信息完整性* – 防止一句话被截断导致语义丢失；
通过 overlap 保证边界处上下文连续。

*长度控制* – 避免超出 embedding 模型最大输入长度，同时保持块足够小以提高检索精度。


A simple data class captures each chunk’s metadata:
@dataclass
class Chunk:
至于text，str # 文本内容
source的观点是，str # 来自哪个文件
index的观点是。int # 文件内自增编号

五、embed：把语义变成数字

The embedding model converts each chunk into a high‑dimensional vector.
from functools import lru_cache
from sentence_transformers import SentenceTransformer
@lru_cache
def get_model -> SentenceTransformer:
return SentenceTransformer
def embed -> list]:
"""批量返回归一化后的向量"""
return get_model.encode.tolist

The @lru_cache-wrapped loader ensures heavy model is loaded only once per process – a direct response to “模型加载慢”痛点。

"normalize_embeddings=True" 把所有向量归一化为单位长度。使得后续矩阵乘直接得到余弦相似度，从而省去额外除法步骤，提高查询效率。

为什么 embedding 不用 DeepSeek？

The DeepSeek service currently only exposes chat/completion APIs and lacks an embedding endpoint. By delegating generation to DeepSeek and retrieval to a local BGE model we achieve:


No extra cost for remote embeddings.

A clear separation of concerns – generation vs retrieval.

Easier debugging because embeddings are fully under our control.
\endul>

六、vector_store + retrieve：检索

A lightweight pure‑numpy store replaces heavyweight vector DBs.
class VectorStore:
def __init__:
self.vectors = np.empty。dtype=np.float32)
self.chunks =
def add:
self.chunks.append
self.vectors = np.vstack])
def search:
# 点积等价余弦，因为已归一化
scores = self.vectors @ qv.T #
order = np.argsort
return


This brute‑force approach runs in microseconds for tens of thousands of chunks – directly addressing “昂贵的向量数据库”痛点。

def retrieve(store: VectorStore,query: str,topk: int = 5,minscore: float = 0.6) -> list:
qvec = np.array)
hits = store.search
return



sequenceDiagram
participant U as 使用者
participant R as retrieve
participant VS as VectorStore
participant E as BGE
U->E这方面。问题文本
再看E-->R，问题向量
再看R->VS，search
再看VS-->R，前 k 个相似块 + 分数
R->U这方面，返回过滤后的块



七、answer：带引用的回答

The final step builds a prompt that forces LLM to cite sources using .

def build_prompt -> str:
context = "
".join)
return f"""只依据下面编号的资料回答问题，用 标注依据，资料没有的说"资料中没有相关信息"。再看资料，{context}
问题这方面，{query}"""


def answer -> dict:
resp = chat) # 调用 DeepSeek API 的封装函数
return {"answer": resp。"chunks": chunks}


资料： 循环引用是两个对象互相持有强引用…使用 weak 弱引用可以打破循环…怎么解决，说到规则，- 只依据资料回答，资料没有说“资料中没有相关信息”。- 用 标注依据，如“内存无法释放 ”。- 每条依据单独占一行，


User Pain Point Addressed: 明确且机器可解析的引用格式防止模型“幻觉”，让审计者能够快速定位答案出处。

八、evaluate：用数字说话

An objective evaluation suite quantifies both retrieval hit rate and citation correctness.

TEST_CASES = 


def extractcitationnums -> list:
return ",text)]

def evaluate -> list:
results =
for query。expected in TESTCASES:
chunks = retrieve
hit = expected in {c.source for c in chunks}
citedsources = {chunks.source for n in extractcitationnums) if n ok = expected in citedsources
results.append)
return results


This numeric feedback loop lets us tune parameters,directly solving “调参无感知”痛点.

九、踩过的坑 & 实践建议 



Intel Mac 兼容性：Torch 在 x8664 上最高只支持特定版本，需要匹配对应 CUDA/CPU wheel；否则会出现导入错误或性能下降。说起来，推荐使用官方 CPU‑only wheel 并锁定 transformers 与 numpy 的兼容版本。

Citation format 不稳定：L​LM 有时会省略方括号或换行。通过在 Prompt 中加入严格示例并使用正则后处理，可明显提高一致性——这直接缓解了“答案不可追溯”的痛点。

Semi‑loose similarity threshold：If minscore is set too low you’ll see irrelevant blocks appear in answer. Empirically 0.6~0.7 works well on our iOS corpus；根据业务调低或调高即可避免“噪声答案”。"

Numpy 全表搜索规模限制： 对于上万甚至百万级文档，可考虑分桶或使用 Faiss 等轻量库。怎么说呢，但在小规模私有知识库里全表搜索已足够快且省去额外部署成本——
体现“低成本、本地化”的优势。"
<\/ol>