SSH-PuR66/policy-scout
GitHub: SSH-PuR66/policy-scout
PolicyScout 是一个受 GAMECHANGER 启发的政策文档语义搜索与引用式问答 pipeline，针对 DoD 公开发文提供混合检索、重排和评估门控。
Stars: 0 | Forks: 0
# PolicyScout
**受 GAMECHANGER 启发的 DoD 政策文档语义搜索。**
**v0.4** — 混合稀疏 BM25+TF-IDF 检索与 RRF 融合，DoD 领域查询扩展（网络作战同义词库），MMR 多样化，带有 **cross-encoder 形状重排器** 的引用式抽取式 QA（引用精度 0.94 → **1.00**），grounded-LLM composer 接口，基于 **12 个查询 / 6 个文档** 集的 nDCG + 引用精度评估门控，带有 **Prometheus 导出** 的 `/metrics`，以及内置的位于 `/` 的 Web UI。
受 [CDAO 分析工具倡议](https://www.ai.mil/Initiatives/Analytic-Tools/) 启发——
特别是 GAMECHANGER 基于 NLP 的政策搜索——PolicyScout 是一个小巧、可复现的
pipeline，用于摄取公开发布的 DoD 发文，对其进行分块和索引，并通过 REST API 和 CLI 提供
语义搜索服务。
完全使用
[专家驱动开发批准工具列表](https://jeranaias.github.io/ExpertDrivenDevelopment/tools/) 中的工具构建：
在公共 GitHub 上开源（非涉密），带有专为
**Azure OpenAI (FedRAMP High)** 配置的可插拔 embedding 后端，以及针对 **Azure Government at IL5** 的部署计划
（参见 [docs/IL5_DEPLOYMENT.md](docs/IL5_DEPLOYMENT.md)）。
## 架构
```
flowchart TD
subgraph Ingest
RAW["data/raw/*.pdf|txt"] --> ING["ingest.py
section-aware chunk
+ reference extraction"] ING --> CH["chunks.jsonl"] end subgraph Index["Retrieval index"] CH --> TFIDF["TF-IDF cosine
(1-2 grams)"] CH --> BM25["sparse BM25
O(docs x query terms)"] end subgraph Query["Per-request pipeline"] Q(["user query"]) --> EXP["query.py
DoD thesaurus expansion"] EXP --> TFIDF EXP --> BM25 TFIDF --> RRF["RRF fusion"] BM25 --> RRF RRF --> MMR["MMR diversify (λ=0.7)"] MMR --> RR["answer.py
LexicalReranker
(cross-encoder seam)"] RR --> COMP["Composer
Extractive | Azure OpenAI Gov"] COMP --> OUT(["cited answer
[doc#chunk]"]) end subgraph Serve CLI["cli.py"] --- MMR API["api.py (FastAPI)
/search /answer /graph
/eval /metrics + UI"] --- MMR API --> PROM["/metrics?format=prometheus"] end subgraph Gate["CI quality gates"] EVAL["evaluate.py
recall · MRR · nDCG
citation precision = 1.0"] end OUT -.audited by.-> EVAL ``` 文本回退（在 Mermaid 无法渲染的任何地方渲染）： ``` raw docs ─► ingest (section chunk + refs) ─► chunks.jsonl │ ┌──────── TF-IDF cosine ◄────────┤ query ─► expand (thesaurus) ├─► BM25 (sparse) └──► RRF fusion ─► MMR ─► reranker ─► composer ─► cited answer │ cli.py api.py (FastAPI + /metrics→Prometheus) │ evaluate.py: recall / MRR / nDCG / citation-precision (CI-gated) ``` - **默认后端完全离线** (TF-IDF)：确定性、可复现，无数据 离开环境——这是针对邻近 CUI 工作流的正确默认安全姿态。 - **`AzureEmbeddingBackend`** 只需更改一项配置即可替换，以便在授权的 Azure Government 边界内提供生产级质量的 语义 embedding。 ## 快速开始 ``` pip install -e ".[dev]" # 可选：拉取真实的公开 DoD 发布文件（DoDD 3000.09、DoDI 5000.89、 # DoDI 5200.48、DoD Data/Analytics/AI Adoption Strategy） python scripts/fetch_corpus.py # 构建索引（在打包的样本语料库上开箱即用） python -m policy_scout.cli index # 从 CLI 搜索 python -m policy_scout.cli search "impact level 5 controlled unclassified information" # 或运行 API uvicorn policy_scout.api:app --app-dir src curl "localhost:8000/search?q=responsible+AI+principles" ``` ## 测试与 CI `pytest` 涵盖了端到端的全流程 pipeline（摄取 → 索引 → 搜索 → API），并且 GitHub Actions 会在每次 push/PR 时，在 Python 3.10 和 3.12 上运行 lint (ruff) + 测试。 ``` pytest -v ``` ## 语料库说明 仓库附带了清晰标记的 **合成示例文档**，以便 pipeline 和 测试可以在任何零网络访问的环境中运行。`scripts/fetch_corpus.py` 会将它们 替换为来自 esd.whs.mil / media.defense.gov 的真实、公开发布的发文。 ## 为什么存在这个项目 旨在展示前沿部署工程师（Forward Deployed Engineer，USAJOBS 2210/GS-14）职位的专业经验能力：技术集成（数据 pipeline + AI/ML）、 端到端软件工程，以及现代 CI/CD——映射到 CDAO 分析 工具生态系统（GAMECHANGER、Advana、JATIC）。
section-aware chunk
+ reference extraction"] ING --> CH["chunks.jsonl"] end subgraph Index["Retrieval index"] CH --> TFIDF["TF-IDF cosine
(1-2 grams)"] CH --> BM25["sparse BM25
O(docs x query terms)"] end subgraph Query["Per-request pipeline"] Q(["user query"]) --> EXP["query.py
DoD thesaurus expansion"] EXP --> TFIDF EXP --> BM25 TFIDF --> RRF["RRF fusion"] BM25 --> RRF RRF --> MMR["MMR diversify (λ=0.7)"] MMR --> RR["answer.py
LexicalReranker
(cross-encoder seam)"] RR --> COMP["Composer
Extractive | Azure OpenAI Gov"] COMP --> OUT(["cited answer
[doc#chunk]"]) end subgraph Serve CLI["cli.py"] --- MMR API["api.py (FastAPI)
/search /answer /graph
/eval /metrics + UI"] --- MMR API --> PROM["/metrics?format=prometheus"] end subgraph Gate["CI quality gates"] EVAL["evaluate.py
recall · MRR · nDCG
citation precision = 1.0"] end OUT -.audited by.-> EVAL ``` 文本回退（在 Mermaid 无法渲染的任何地方渲染）： ``` raw docs ─► ingest (section chunk + refs) ─► chunks.jsonl │ ┌──────── TF-IDF cosine ◄────────┤ query ─► expand (thesaurus) ├─► BM25 (sparse) └──► RRF fusion ─► MMR ─► reranker ─► composer ─► cited answer │ cli.py api.py (FastAPI + /metrics→Prometheus) │ evaluate.py: recall / MRR / nDCG / citation-precision (CI-gated) ``` - **默认后端完全离线** (TF-IDF)：确定性、可复现，无数据 离开环境——这是针对邻近 CUI 工作流的正确默认安全姿态。 - **`AzureEmbeddingBackend`** 只需更改一项配置即可替换，以便在授权的 Azure Government 边界内提供生产级质量的 语义 embedding。 ## 快速开始 ``` pip install -e ".[dev]" # 可选：拉取真实的公开 DoD 发布文件（DoDD 3000.09、DoDI 5000.89、 # DoDI 5200.48、DoD Data/Analytics/AI Adoption Strategy） python scripts/fetch_corpus.py # 构建索引（在打包的样本语料库上开箱即用） python -m policy_scout.cli index # 从 CLI 搜索 python -m policy_scout.cli search "impact level 5 controlled unclassified information" # 或运行 API uvicorn policy_scout.api:app --app-dir src curl "localhost:8000/search?q=responsible+AI+principles" ``` ## 测试与 CI `pytest` 涵盖了端到端的全流程 pipeline（摄取 → 索引 → 搜索 → API），并且 GitHub Actions 会在每次 push/PR 时，在 Python 3.10 和 3.12 上运行 lint (ruff) + 测试。 ``` pytest -v ``` ## 语料库说明 仓库附带了清晰标记的 **合成示例文档**，以便 pipeline 和 测试可以在任何零网络访问的环境中运行。`scripts/fetch_corpus.py` 会将它们 替换为来自 esd.whs.mil / media.defense.gov 的真实、公开发布的发文。 ## 为什么存在这个项目 旨在展示前沿部署工程师（Forward Deployed Engineer，USAJOBS 2210/GS-14）职位的专业经验能力：技术集成（数据 pipeline + AI/ML）、 端到端软件工程，以及现代 CI/CD——映射到 CDAO 分析 工具生态系统（GAMECHANGER、Advana、JATIC）。
标签：Azure OpenAI, BM25, TF-IDF, 大语言模型蜜罐, 文档问答系统, 检索增强生成 (RAG), 网络测绘, 自定义请求头, 语义搜索, 逆向工具