# GovItem_Embedding **Repository Path**: naza/GovItem_Embedding ## Basic Information - **Project Name**: GovItem_Embedding - **Description**: 本基线测试系统旨在评估不同嵌入模型或优化手段在政府事项检索任务中的性能表现。系统通过以下步骤实现： 生成政府事项文本和对应问题文本的向量表示 计算问题向量与事项向量之间的相似度 分析相似度结果，计算各项性能指标 生成可视化报告展示测试结果 - **Primary Language**: Python - **License**: Apache-2.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 1 - **Forks**: 0 - **Created**: 2025-10-17 - **Last Updated**: 2025-12-19 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 政府事项嵌入测试说明 本文档详细介绍政府事项嵌入测试系统的算法、模型、工作流程及相关组件说明。 ## 1. 系统概述 本基线测试系统旨在评估不同嵌入模型或优化手段在政府事项检索任务中的性能表现。系统通过以下步骤实现： 1. 生成政府事项文本和对应问题文本的向量表示 2. 计算问题向量与事项向量之间的相似度 3. 分析相似度结果，计算各项性能指标 4. 生成可视化报告展示测试结果 ## 2. 算法与模型 ### 2.1 嵌入模型 系统支持两种嵌入模型提供商，可以通过配置选项进行切换： - **Ollama模型**（默认） - 模型名称：`qwen3-embedding:0.6b` - 服务地址：`http://localhost:11434` - **OpenAI兼容API模型** - 模型名称：`text-embedding-3-small`（默认） - API密钥：从环境变量`OPENAI_API_KEY`获取 - API地址：从环境变量`OPENAI_BASE_URL`获取（默认为`https://api.openai.com/v1`） ### 2.2 相似度计算算法 系统使用**余弦相似度**算法计算向量之间的相似度： ```python def cosine_similarity(vec1, vec2): # 计算向量点积 dot_product = np.dot(vec1, vec2) # 计算向量范数 norm1 = np.linalg.norm(vec1) norm2 = np.linalg.norm(vec2) # 避免除以零 if norm1 == 0 or norm2 == 0: return 0.0 # 返回余弦相似度 return dot_product / (norm1 * norm2) ``` 余弦相似度的取值范围在[-1, 1]之间，值越大表示两个向量越相似。 ## 3. 工作流程 基线测试包含四个主要步骤，每个步骤由独立的Python脚本实现： ### 3.1 步骤一：向量生成 (step1_embedding.py) **功能**：生成政府事项和问题的向量表示。 **主要流程**： 1. 初始化选定的嵌入模型（Ollama或OpenAI） 2. 读取`dataset/items/`目录下的事项文本文件和`dataset/questions/`目录下的问题文本文件 3. 为每个文件生成唯一的item_id（基于文件名的MD5哈希） 4. 使用嵌入模型将文本转换为向量 5. 将向量保存到`embeddings/items/`和`embeddings/questions/`目录 **数据处理逻辑**： - 仅处理同时存在事项文件和问题文件的条目 - 生成的向量文件包含item_id和embedding两个字段 ### 3.2 步骤二：相似度计算 (step2_similarity_computation.py) **功能**：计算问题向量与所有事项向量之间的相似度。 **主要流程**： 1. 加载所有事项和问题的向量文件 2. 对每个问题向量，计算其与所有事项向量的余弦相似度 3. 按相似度降序排序，保留前10个最相似的事项 4. 将相似度计算结果保存到`similarity/`目录 **输出格式**： - 每个问题文件对应一个相似度结果JSON文件 - 结果包含question_item_id、question_index和recalled_items（包含item_id和score） ### 3.3 步骤三：相似度分析 (step3_similarity_analysis.py) **功能**：分析相似度计算结果，生成各项统计指标。 **分析内容**： 1. **基本统计信息** - 总问题数、总事项数 - 每个问题平均召回事项数 - 平均相似度分数、平均Top1相似度分数 - 最小/最大相似度分数、标准差 2. **召回率指标** - 事项召回率：被召回的唯一事项数 / 总唯一事项数 - 问题命中率：命中的问题数 / 总问题数 - 整体累积召回率：在不同top-n位置命中的比例 3. **相似度分布分析** - 高相似度（≥0.8）、中相似度（0.5-0.8）、低相似度（<0.5）的分布情况 **输出**： - 分析结果保存到`analysis/similarity_analysis_stats.json` ### 3.4 步骤四：报告生成 (step4_generate_report.py) **功能**：根据分析结果生成可视化报告。 **报告内容**： 1. **基本统计信息可视化** - 问题与事项数量对比柱状图 - 相似度分数指标柱状图 - 每个问题平均召回事项数饼图 - 相似度分数分布直方图 2. **召回率分析可视化** - 累积召回率曲线 - Top-n命中率柱状图 3. **相似度分布可视化** - 相似度分数分布饼图 - 相似度区间分布柱状图 **输出**： - 可视化图表保存到`report/images/`目录 - Markdown格式报告保存到`report/availability_analysis_report.md` ## 4. 目录结构 ``` GovItem_Embedding/ ├── dataset/ # 数据集目录 │ ├── items/ # 政府事项文本文件 │ └── questions/ # 对应问题文本文件 ├── baseline/ # 基线测试目录 │ ├── step1_embedding.py # 向量生成脚本 │ ├── step2_similarity_computation.py # 相似度计算脚本 │ ├── step3_similarity_analysis.py # 相似度分析脚本 │ ├── step4_generate_report.py # 报告生成脚本 │ ├── embeddings/ # 向量存储目录 │ │ ├── items/ # 事项向量 │ │ └── questions/ # 问题向量 │ ├── similarity/ # 相似度计算结果 │ ├── analysis/ # 分析结果 │ └── report/ # 报告输出目录 │ ├── images/ # 可视化图表 │ └── availability_analysis_report.md # 分析报告 ├── requirements.txt # 依赖包列表 └── step0_gen_questions.py # 问题生成脚本 ``` ## 5. 数据结构 ### 5.1 向量文件格式 事项和问题向量文件采用JSON格式存储，结构如下： ```json { "item_id": "8f7d3c2b1a0e9d8c7b6a5f4e3d2c1b0a", // 基于文件名生成的MD5哈希 "embedding": [0.123, 0.456, 0.789, ...] // 向量表示，浮点数数组 } ``` ### 5.2 相似度结果文件格式 ```json [ { "question_item_id": "8f7d3c2b1a0e9d8c7b6a5f4e3d2c1b0a", // 问题对应的事项ID "question_index": 0, // 问题索引 "recalled_items": [ // 召回的事项列表 { "item_id": "8f7d3c2b1a0e9d8c7b6a5f4e3d2c1b0a", // 召回事项的ID "score": 0.9876 // 相似度分数 }, ... // 更多召回事项 ] }, ... // 更多问题的召回结果 ] ``` ### 5.3 分析结果文件格式 ```json { "basic_statistics": { "total_questions": 100, "total_items": 50, "avg_recalled_items_per_question": 10, "avg_similarity_score": 0.95, "avg_top1_similarity_score": 0.98, "min_similarity_score": 0.8, "max_similarity_score": 0.999, "std_similarity_score": 0.02 }, "recall_metrics": { "items_recall_rate": 1.0, "questions_hit_rate": 0.95, "overall_cumulative_recall": { "top1_recall_rate": 0.8, "top5_recall_rate": 0.92, "top10_recall_rate": 0.95 } }, "similarity_distribution": { "high_similarity_count": 800, "medium_similarity_count": 200, "low_similarity_count": 0, "total_scores": 1000 } } ``` ## 6. 依赖包 系统使用以下Python包： ``` langchain>=0.1.0 # LangChain核心库 openai>=1.0.0 # OpenAI API客户端 python-dotenv>=1.0.0 # 环境变量管理 pydantic>=2.0.0 # 数据验证 langchain_community>=0.3.0 # LangChain社区组件 langchain-openai>=0.3.0 # LangChain OpenAI集成 langchain-ollama>=0.3.0 # LangChain Ollama集成 langchain-core>=0.3.0 # LangChain核心功能 numpy>=1.20.0 # 数值计算 pandas>=2.0.0 # 数据分析 matplotlib>=3.7.0 # 绘图库 seaborn>=0.12.0 # 统计数据可视化 tqdm>=4.66.0 # 进度显示 ``` ## 7. 运行说明 按照以下顺序运行各脚本，完成基线测试： 1. 确保安装了所有依赖包：`pip install -r requirements.txt` 2. 确保已准备好数据集（事项和问题文本文件） 3. 运行向量生成脚本：`python step1_embedding.py` 4. 运行相似度计算脚本：`python step2_similarity_computation.py` 5. 运行相似度分析脚本：`python step3_similarity_analysis.py` 6. 运行报告生成脚本：`python step4_generate_report.py` ## 8. 配置说明 在`step1_embedding.py`中可以修改以下配置： ```python # 选择向量模型提供者: 'ollama' 或 'openai' EMBEDDINGS_PROVIDER = 'ollama' # 可以切换为 'openai' # Ollama配置 OLLAMA_MODEL = 'qwen3-embedding:0.6b' # Ollama向量模型 OLLAMA_BASE_URL = 'http://localhost:11434' # OpenAI兼容API配置 OPENAI_MODEL = 'text-embedding-3-small' # 或其他兼容的模型 ``` ## 9. 结果解读 基线测试主要关注以下几个指标： 1. **Top-1准确率**：最相似结果即为正确结果的比例 2. **Top-k召回率**：在前k个结果中包含正确结果的比例 3. **平均相似度分数**：所有召回结果的平均相似度 4. **相似度分布**：不同相似度区间的结果分布 这些指标可以帮助评估嵌入模型在政府事项检索任务中的性能表现，为模型选择和优化提供参考。 ## 10. 注意事项 1. 运行前确保数据集目录结构正确 2. 使用OpenAI模型时，需正确配置API密钥 3. 使用Ollama模型时，需确保本地Ollama服务正常运行 4. 生成的向量和中间结果会覆盖现有文件，如需保留历史结果请提前备份 5. 报告生成过程中会清除并重建报告目录 ## 11. 模型修改与优化测试方法 当需要测试不同的嵌入模型或采用优化手段时，请按照以下步骤操作： ### 11.1 创建测试子目录 在项目根目录下创建新的测试子目录，建议使用具有描述性的命名，如`optimized_embeddings`或`model_comparison`等： ```bash mkdir -p c:\UGit\GovItem_Embedding\your_test_directory ``` ### 11.2 复制基线脚本 将baseline目录中的所有脚本复制到新创建的测试子目录： ```bash # 复制所有Python脚本 copy c:\UGit\GovItem_Embedding\baseline\*.py c:\UGit\GovItem_Embedding\your_test_directory # 创建必要的子目录结构 mkdir -p c:\UGit\GovItem_Embedding\your_test_directory\embeddings\items mkdir -p c:\UGit\GovItem_Embedding\your_test_directory\embeddings\questions mkdir -p c:\UGit\GovItem_Embedding\your_test_directory\similarity mkdir -p c:\UGit\GovItem_Embedding\your_test_directory\analysis mkdir -p c:\UGit\GovItem_Embedding\your_test_directory\report\images ``` ### 11.3 调整模型参数或优化方法 根据测试需求，修改复制到测试子目录中的脚本： 1. **更改嵌入模型**：修改`step1_embedding.py`中的模型配置 ```python # 例如，更改为不同的Ollama模型 OLLAMA_MODEL = 'llama3-embed:8b' # 或更改为不同的OpenAI模型 OPENAI_MODEL = 'text-embedding-3-large' ``` 2. **实现优化方法**：可以对任何脚本进行修改以实现优化，例如： - 在`step1_embedding.py`中添加文本预处理优化 - 在`step2_similarity_computation.py`中实现更高效的相似度计算算法 - 在`step3_similarity_analysis.py`中添加新的评估指标 ### 11.4 运行测试 按照与基线测试相同的顺序运行脚本： ```bash cd c:\UGit\GovItem_Embedding\your_test_directory python step1_embedding.py python step2_similarity_computation.py python step3_similarity_analysis.py python step4_generate_report.py ``` ### 11.5 编写测试说明文档 在测试子目录中创建`README.md`文件，记录测试的详细信息： ```markdown # 测试说明：[测试名称] ## 测试目的 简要说明本次测试的目标，如： - 测试特定嵌入模型在政府事项检索任务中的表现 - 验证特定优化方法对检索性能的影响 ## 测试配置 ### 模型配置 - 使用的嵌入模型：[模型名称] - 模型参数：[参数详情] - 环境配置：[相关环境设置] ### 优化方法 详细描述实现的优化方法或改进： 1. [优化点1] 2. [优化点2] 3. ... ## 测试结果 ### 与基线对比 - Top-1准确率：[提升/下降百分比] - Top-5召回率：[提升/下降百分比] - 平均相似度分数：[提升/下降百分比] ### 性能分析 分析测试结果，解释改进或退化的原因。 ## 结论 总结本次测试的发现和建议。 ``` ### 11.6 结果对比 为了方便对比不同测试的结果，可以： 1. 创建结果汇总表格，对比各个测试的关键指标 2. 保存并归档各个测试的报告目录，便于后续查阅 3. 考虑创建一个集中的结果管理工具，自动收集和比较不同测试的结果 通过这种方法，可以系统地测试和评估不同模型和优化方法的效果，为最终的生产环境选择提供可靠依据。