Django 搭建 AI 本地知识库：文档上传、向量检索与智能问答

把 PDF 上传到服务器。再调用一次大模型，并不等于拥有“本地知识库”。一个真正可用的 Django 知识库至少要解决六件事：文件归属、文本切块、向量生成、相似度检索、权限过滤和答案引用。怎么说呢，

这篇文章以 PostgreSQL、pgvector 和 Django ORM 为主线。并把方案放进本地 RuyiDjangoCRM 的文档与多租户搜索边界中验证。最关键的结论是：先确定使用者能看哪些文档，再在可见集合内做向量排序；不能先搜全库再补权限，

一条完整的知识库链路

痛点1：原始文件保留 vs. 检索效率冲突

上传后的原始文件仍然要保留，便于重新解析和审计；真正用于检索的是切块后的文本。按理说，每个文本块至少记录：

• org_id + document_id；
• position；
• content_hash；
• embedding_model:version。

痛点2：PostgreSQL 安装混乱？一次搞定，

pip install pgvector psycopg
CREATE EXTENSION IF NOT EXISTS vector;-- 确保使用 pgvector v0.5.1+ 支持 HNSW
ALTER TABLE knowledgechunk ADD COLUMN embedding VECTOR;CREATE INDEX chunkembeddinghnsw ON knowledgechunk USING hnsw;-- 对比传统 GIN 索引速度提高5-10倍！sql

用 Django 模型保存文本块和向量

python from django.db import models from pgvector.django import HnswIndex,VectorField

class KnowledgeChunk: org_id = models.UUIDField # 必须加快查询组织可见性 document = models.ForeignKey position = models.PositiveIntegerField # 用于精准定位回源

content = models.TextField
content_hash = models.CharField # SHA256
embedding_model = models.CharField
embedding = VectorField # 必须匹配 embeddings-as-service 输出
class Meta:
constraints =。name="uq_document_chunk_hash",)
]
indexes =,m=16,ef_construction=100,opclasses=,)
]

`` **关键设计选择**： 1. **版本化处理**：embedding_model`字段记录生成时间戳+模型ID，避免不同维度混淆 2. 性能调整HNSW近邻搜索配置参数已调整为公司级数据规模常用方法

切块不是越碎越好 - 结构化分片才是王道！

python def smart_chunking -> Generator: """保留语义边界的分片算法""" blocks = re.split||'。text) # 分割句子/段落 for block in blocks: if len)> size: for chunk in simple_overlap_split,size,overlap): yield chunk.strip elif block.strip: yield block.strip 为什么简单字符数切割会失败？

先做权限过滤，再做向量排序 - 安全设计主要！

python @requirespermission def searchwithpermissions: """安全前置式查询""" visibleqs = KnowledgeChunk.objects.filter( orgid=userprofile.orgid,documentin=getvisible_documents )

return visible_qs.annotate(
score=CosineDistance
).order_by

安全漏洞对比表

让回答带上可核验引用 - 提高使用者信任度!

python def generate_answer_with_sources: prompt_template = f""" 基于以下资料严格回答问题： {build_citation_prompt} 若无这些内容请明确说明"未找到直接答案" """ return call_model 引用链路示例 说到问题，"如何申请年假？" 回答这方面，"根据公司手册第9条规则 ..."

验证暴露出的两个致命误区!

误区#1：只测"能搜到" ✅ 应该测试： ✔ 跨组织隔离 ✔ 最小特权原则

误区#2：忽略版本控制 ⚠️ 风险： • 模型迭代导致旧数据无效化 • 法律合规要求历史版本可回溯

结论 - 三大主要原则!

1. 端到端追溯性每条答案必须关联回源
2. 零信任架构所有查询必须层
3. 渐进式部署从关键词验证→语义嵌入→端到端测试分阶段推进