English | 简体中文
OptiAgent 是一个面向光学工程资料的本地优先 AI 助手。它将结构化镜头处方检索、玻璃目录查询、向量与全文混合检索、LangGraph 工具调用和 Streamlit 工作台放在同一个项目中。
项目的本地检索、镜头处方查询与玻璃查询不需要调用大语言模型。只有使用 Agent 对话时，检索到的上下文才会发送给你配置的 OpenAI 兼容模型端点；该端点可以是本机服务，也可以是远程服务。
OptiAgent 是资料检索与工程辅助工具，不是光学追迹、玻璃认证或设计结果验证软件。镜头处方摘要不代表性能验证，玻璃候选排名也不能视为可直接替换结论。
本项目界面演示，实际输出取决于你配置的模型和本地资料。
| 能力 | 当前实现 |
|---|---|
| 结构化镜头库 | 解析 Zemax 文本处方中的 NAME、ENPD、SURF、STOP、GLAS、视场与波长记录；支持名称、源文件、材料和表面数过滤 |
| 结构化玻璃查询 | 解析 Zemax/AGF 的 NM、GC、ED、CD 记录；支持名称、目录、nd、Vd 范围过滤 |
| 玻璃候选初筛 | 依据标准化后的 nd、Vd 与可用密度计算属性距离，并明确返回非验证性提示 |
| 混合检索 | Chroma 向量检索与 SQLite FTS5 稀疏检索，经 Reciprocal Rank Fusion 合并 |
| 本地模型 | 嵌入模型在本地运行；重排模型可选并按需加载 |
| 增量摄入 | 文件 SHA-256 清单、每文件独立 chunk 归属、稳定 chunk ID、批量嵌入、删除与更新检测，并阻止不兼容索引配置混用 |
| 文档清理 | 编码与质量检测、控制字符清理、代码缩进保留、结构化格式解析、PDF 页眉页脚过滤及标题上下文 |
| 可审计流式 Agent | 回答逐步输出，可查看阶段摘要、工具调用与检索证据，不展示隐藏思维链；发送给模型的历史轮数可配置，避免长会话上下文无限增长 |
| 中英文工作台 | 侧栏可即时切换中文与 English，导航、状态、表单、提示和结果列名同步更新 |
| 可复现评估 | 仓库内置确定性检索用例，报告 Top-1、单文档与聚合关键词命中、关键词/来源 MRR 和延迟 |
flowchart LR
D[Manual / CamLibrary / Glasscat / Macro] --> I[Incremental ingestion]
I --> V[(Chroma vector index)]
I --> S[(SQLite FTS5 index)]
Q[User query] --> R[Deterministic source routing]
R --> V
R --> S
V --> F[RRF fusion]
S --> F
F --> X[Optional local reranker]
Q --> P[Structured lens catalog]
Q --> G[Structured AGF catalog]
X --> A[LangGraph tools]
P --> A
G --> A
A --> L[Configured chat model]
L --> U[CLI / Streamlit]
git clone https://github.com/LyraZeta/OptiAgent.git
cd OptiAgent
python -m venv .venvWindows PowerShell：
.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
pip install -e .
Copy-Item .env.example .envmacOS / Linux：
source .venv/bin/activate
python -m pip install --upgrade pip
pip install -e .
cp .env.example .envoptiagent models如需启用可选重排模型：
optiagent models --with-reranker下载后在 .env 中设置 OPTIAGENT_RERANKER=on 才会启用。默认关闭，以避免每次查询增加重排延迟；是否启用应以你自己的评估集结果为准。
也可以在 .env 中指向已下载的本地模型。封闭网络环境请先准备模型文件，并设置 OPTIAGENT_OFFLINE=true。
将你有权使用的资料放入以下目录：
data/
├── Manual/ # 手册、书籍或说明文档
├── CamLibrary/ # 镜头处方与镜头库文本
├── Glasscat/ # AGF 或玻璃目录文本
└── Macro/ # ZPL 等宏文件与说明
首次建立 v3 索引：
optiagent ingest --reset
optiagent doctor后续执行 optiagent ingest 只处理新增、修改或删除的文件。若嵌入模型、Chroma collection、chunk 参数或索引结构发生变化，命令会拒绝混用旧索引并提示使用 --reset。从 v2 升级后必须执行一次 optiagent ingest --reset。
摄入器会按来源类型解析数据，而不是把所有文件当作普通文本：JSON 顶层记录、CSV/TSV 表头行、HTML 可见文本、XML 元素路径、AGF NM 记录、Zemax 系统/SURF/操作数区段，以及 ZPL 代码都会保留对应结构和元数据。支持 .txt、.md、.csv、.tsv、.json、.xml、.html、.agf、.zmx、.zpl 与带文本层的 PDF；项目当前不包含 OCR 管线。
无需 LLM 的混合检索：
optiagent search "赛德尔五种初级像差包括哪些？"无需 LLM 的结构化镜头处方筛选：
optiagent lens --query landscape --material BK7 --max-surfaces 10该命令读取文件中明确存在的处方元数据，不计算焦距、像质、可制造性或设计有效性。
无需 LLM 的结构化玻璃查询：
optiagent glass --manufacturer SCHOTT --min-nd 1.70 --limit 10
optiagent substitute N-BK7 --reference-catalog SCHOTT --target-catalog OHARA --limit 5第二条命令只输出属性距离排名，不验证热学、机械、工艺、供应或系统级可替换性。
在 .env 中填写 OpenAI 兼容端点：
LLM_MODEL=your-model-name
OPENAI_COMPAT_BASE_URL=http://127.0.0.1:8000/v1
OPENAI_COMPAT_API_KEY=your-key然后启动界面：
optiagent serve默认地址为 http://127.0.0.1:8501。若配置远程端点，界面会提示检索上下文可能离开本机。
网页会保留当前会话的全部可见消息；发送给模型的历史默认只保留最近 8 轮，可通过 OPTIAGENT_CHAT_HISTORY_TURNS 调整，避免长会话持续增加 Token 和延迟。
optiagent doctor 检查配置、索引、镜头库和玻璃目录状态
optiagent ingest 建立或增量更新向量与稀疏索引
optiagent search 执行本地混合检索
optiagent lens 按处方元数据筛选本地镜头库
optiagent glass 按结构化字段筛选玻璃
optiagent substitute 按目录属性距离排列候选玻璃
optiagent chat 执行一次 Agent 对话
optiagent evaluate 运行确定性检索评估
optiagent models 下载本地检索模型
optiagent serve 启动 Streamlit 工作台
使用 optiagent <command> --help 查看完整参数。
确定性检索评估不调用聊天模型：
optiagent evaluate报告会写入 eval/results/，该目录中的生成结果不会提交到 Git。这里的关键词命中和来源命中只衡量当前检索用例，不等价于答案正确率、忠实度或通用基准成绩。
运行单元测试：
python -m unittest discover -s tests -v开发环境与静态检查：
pip install -e ".[dev]"
ruff check .
mypy agent data_prep eval optiagent tools app.py.env、模型权重、向量数据库、稀疏索引和生成报告默认不进入 Git。data/private/用于明确不应同步的本地资料。- 远程 LLM 会接收到为回答问题而检索出的文本片段；敏感资料应使用本地模型端点。
- MIT 许可证覆盖本项目代码，不自动覆盖
data/中可能来自第三方的手册、目录或书籍。
提交或分发资料前，请阅读 DATA_POLICY.md。安全问题与密钥处理见 SECURITY.md。
hpc_scripts/ 提供基于 ssh 与 rsync 的代码、wheelhouse 和环境归档传输脚本。它们默认排除 .env、模型、私有数据、索引和整个 data/ 目录；只有显式设置 OPTIAGENT_SYNC_DATA=1 才会同步数据。详见 hpc_scripts/README.md。
- PDF 解析依赖文本层；扫描件需先由外部 OCR 工具处理。
- 来源路由采用可读的确定性规则，并不保证每个问题都路由到最佳语料。
- 检索质量取决于资料质量、嵌入模型和用例覆盖范围。
- Agent 最终回答取决于所配置的聊天模型，项目不会把 LLM 输出视为已验证工程结论。
- 镜头库只汇总文本处方中明确记录的字段，不计算焦距、像差、MTF、公差或可制造性。
- 玻璃属性距离没有包含完整色散曲线、热学、机械、工艺、价格或供货状态。
欢迎提交可复现的问题、测试和小范围改进。请先阅读 CONTRIBUTING.md，不要在 issue、PR 或测试夹具中提交 API Key、私有资料或无授权的第三方内容。
项目代码采用 MIT License。数据与第三方资料的权利边界见 DATA_POLICY.md。