测试工程师指南：基于需求文档构建本地安全知识库的完整实战

需求文档是测试工程师日常工作的核心工具，如何快速检索需求文档中的关键信息（文本、表格、图片等），并将其转化为可供 AI 查询的知识库，是提升工作效率的重要手段。本文将通过对 需求文档（docx 格式） 的处理，详细讲解如何构建一个 安全的本地知识库 ，并通过代码实现具体操作，确保每一步都可落地。

一、本地知识库的安全性与连接方案

在构建本地知识库时，安全性是首要考虑的因素，尤其是对于需求文档这样的敏感数据。以下是本地知识库的安全性与连接方案：

1. 数据隐私 ：本地知识库完全在本地设备运行，避免将敏感文档上传到云端，确保数据隐私。
2. 持久化存储 ：通过 Chroma 的持久化功能，将向量数据库以 SQLite 文件形式保存在本地磁盘。
3. 访问控制 ：通过操作系统的权限管理（如文件夹加密、用户权限设置），限制知识库的访问。
4. 脱离网络运行 ：知识库和向量计算完全在本地运行，无需联网即可完成所有操作。 以下所有代码均基于本地运行，适配 Windows、Mac 和 Linux 环境。

二、需求文档处理与向量化的完整流程图

针对需求文档（docx 格式），我们需要将文档中的 文本、表格、图片 等内容提取并向量化。以下是完整流程图： +——————————————-+ | 需求文档加载 | | 使用 python-docx 提取 docx 文件内容 | | 支持文本、表格、图片 | +——————————————-+ ↓ +——————————————-+ | 数据清洗 | | 移除空行、无效字符，提取关键信息 | +——————————————-+ ↓ +——————————————-+ | 文本分割 | | 将文本分割为小段（500字左右） | | 表格转化为结构化文本 | +——————————————-+ ↓ +——————————————-+ | 文本向量化 | | 使用中文预训练模型生成向量 | +——————————————-+ ↓ +——————————————-+ | 图片向量化 | | 使用 OpenAI CLIP 模型生成图片向量 | +——————————————-+ ↓ +——————————————-+ | 存储到向量数据库 | | 使用 Chroma 将向量和原始数据存储 | +——————————————-+ ↓ +——————————————-+ | 本地知识库检索 | | 根据用户输入，检索最相关的文档片段 | +——————————————-+

三、处理需求文档的完整实例（docx 格式）

1 环境准备

安装以下 Python 库： pip install python-docx chromadb sentence-transformers PIL

2 加载需求文档

使用 python-docx 提取 docx 文件中的内容（包括文本与表格）。对于图片，则使用 PIL 进行处理。 以下是提取需求文档的代码： from docx import Document from PIL import Image from io import BytesIO import os

提取文本和表格

def extract_text_and_tables(docx_path): document = Document(docx_path) texts = [] tables = []

提取段落文本

for paragraph in document.paragraphs: if paragraph.text.strip(): # 去掉空行 texts.append(paragraph.text.strip())

提取表格内容

for table in document.tables: table_data = [] for row in table.rows: row_data = [cell.text.strip() for cell in row.cells] table_data.append(row_data) tables.append(table_data) return texts, tables

提取图片

def extract_images(docx_path, output_folder): document = Document(docx_path) os.makedirs(output_folder, exist_ok=True) image_paths = [] for rel in document.part.rels.values(): if “image” in rel.target_ref: image_data = rel.target_part.blob image = Image.open(BytesIO(image_data)) image_path = os.path.join(output_folder, f"image_{len(image_paths)+1}.png") image.save(image_path) image_paths.append(image_path) return image_paths

示例：提取需求文档内容

docx_path = “requirement_document.docx” output_folder = “extracted_images” texts, tables = extract_text_and_tables(docx_path) image_paths = extract_images(docx_path, output_folder) print(f"提取文本段落：{len(texts)} 段") print(f"提取表格：{len(tables)} 个") print(f"提取图片：{len(image_paths)} 张")

3 数据清洗与分割

数据清洗

对提取的文本和表格进行清洗，移除无效字符和空白内容： import re

清洗文本

def clean_text(text): text = re.sub(r"\s+", " “, text) # 移除多余空白 text = re.sub(r”[^\u4e00-\u9fa5a-zA-Z0-9，。！？；：]", “”, text) # 移除特殊字符 return text cleaned_texts = [clean_text(text) for text in texts]

转换表格为结构化文本

def table_to_text(table): return “\n”.join([" | “.join(row) for row in table]) cleaned_tables = [table_to_text(table) for table in tables] print(“清洗完成！”)

文本分割

将文本和表格分割为适合向量化的小段（每段 500 字左右）： from langchain.text_splitter import CharacterTextSplitter

分割文本

text_splitter = CharacterTextSplitter(chunk_size=500, chunk_overlap=50) documents = text_splitter.split_text("\n”.join(cleaned_texts + cleaned_tables)) print(f"分割为 {len(documents)} 个片段")

4 文本与图片向量化

文本向量化

使用 sentence-transformers 的中文模型生成文本向量： from sentence_transformers import SentenceTransformer

加载中文预训练模型

model = SentenceTransformer(“damo/nlp_corom_sentence-embedding_chinese-base”)

向量化文本片段

text_embeddings = model.encode(documents) print(f"生成了 {len(text_embeddings)} 个文本向量")

图片向量化

使用 OpenAI 的 CLIP 模型生成图片向量： pip install open_clip_torch import open_clip import torch from PIL import Image

加载 CLIP 模型

model, preprocess = open_clip.create_model_and_transforms(‘ViT-B-32’, pretrained=‘openai’) tokenizer = open_clip.get_tokenizer(‘ViT-B-32’)

向量化图片

image_embeddings = [] for image_path in image_paths: image = preprocess(Image.open(image_path)).unsqueeze(0) # 预处理图片 with torch.no_grad(): image_embedding = model.encode_image(image) image_embeddings.append(image_embedding.numpy()) print(f"生成了 {len(image_embeddings)} 个图片向量")

5 存储到 Chroma 向量数据库

将文本与图片的向量及原始数据存储到 Chroma 中： import chromadb

初始化数据库

client = chromadb.PersistentClient(path="./chroma_knowledge_base")

创建集合

collection = client.get_or_create_collection(name=“requirement_docs”)

存储文本向量

collection.add( documents=documents, # 原始文本 embeddings=text_embeddings, # 文本向量 ids=[f"text_{i}" for i in range(len(documents))] )

存储图片向量

collection.add( documents=image_paths, # 图片路径 embeddings=image_embeddings, # 图片向量 ids=[f"image_{i}" for i in range(len(image_paths))] ) print(“成功存储文本与图片向量”)

6 本地知识库检索

根据用户输入的问题，检索相关文本或图片：

用户输入问题

query = “登录界面的设计要求是什么？” query_embedding = model.encode([query])

检索最相关的结果

results = collection.query( query_embeddings=query_embedding, n_results=5 )

打印检索结果

for i, doc in enumerate(results[“documents”][0]): print(f"相关结果 {i+1}：{doc}")

四、小结

本文介绍了如何针对需求文档（docx 格式）构建本地知识库的完整流程，包括 文本、表格、图片的提取与向量化 ，并结合 Chroma 数据库实现了安全的本地存储与检索。以下是本地知识库的关键特点：

1. 完全本地化 ：所有处理和存储均在本地设备完成，无需联网，确保数据隐私。
2. 支持多模态数据 ：同时支持文本和图片的检索，满足复杂文档的需求。
3. 落地性强 ：代码清晰可用，测试工程师可以直接应用于日常工作中。 通过这种方式，测试工程师可以快速构建起属于自己的安全本地知识库，大幅提升工作效率！