MARITIME RAG · EVIDENCE GOVERNANCE · SOP COPILOT 小懿 AI · 港航行业智能问答与SOP决策助手 Xiaoyi AI · Evidence-Grounded Maritime RAG & Operations Copilot 研发作者：温家懿 · Research Author: Wen Jiayi 把港航问答从“模型说了什么”，提升为“证据来自哪里、适用于哪个辖区和日期、何时必须拒答、谁允许推进任务”的可审计决策链。 A governance-first maritime assistant where retrieval, jurisdiction, temporal applicability, refusal, task progression, and audit evidence are independently reviewable. 112 登记文档 · 708 知识分块 · 60 官方来源 · 11/11 证据策略门禁

核心指标 / Evidence · 能力全景 / Capabilities · 系统架构 / Architecture · 快速运行 / Quick start · 基准报告 / Benchmark · RL证据 / RL evidence · 开源审计 / Audit

_{固定证据总览：同屏核对三套数据血缘、五算法矩阵、观测/动作/目标、小懿训练顾问和后端按钮联动。}

flowchart LR
  subgraph Sources["Knowledge & Runtime Sources / 知识与运行来源"]
    KB["112 docs / 708 chunks"]
    REG["Authority registry\n官方来源与辖区"]
    OPS["Sandbox or verified live adapter\n沙箱或验证实时适配器"]
  end
  subgraph Intelligence["Evidence Intelligence / 证据智能"]
    HYB["Hybrid Sparse + BM25"]
    ROUTE["Jurisdiction + effective date"]
    POLICY["Citation · refusal · privacy gates"]
    LLM["Local rules / optional compatible gateway"]
  end
  subgraph Workflow["Human-Gated Workflow / 人工门禁工作流"]
    CHAT["SSE chat + structured answer"]
    SOP["SOP task + report"]
    AUDIT["Receipt + audit persistence"]
  end
  KB --> HYB
  REG --> ROUTE --> HYB --> POLICY
  OPS --> POLICY
  POLICY --> LLM --> CHAT
  CHAT --> SOP --> AUDIT

小懿AI/
  app/
    main.py              # FastAPI服务入口 / service entry
    operations.py        # 运营、任务与报告API / operations, tasks, reports
    port_runtime.py      # 沙箱/生产数据适配器 / sandbox/live adapters
    rl_lab/              # 数据、4种RL、PID与评估 / data, 4 RL, PID, evaluation
    operator_assistant.py # 一线口语与对象追问 / frontline language and clarification
    xiaoyi.py            # 小懿回答引擎 / answer engine
    retrieval.py         # Hybrid Sparse与BM25对照 / retrieval and baseline
    prompts.py           # 港航专业提示词 / maritime prompts
    models.py            # 请求与响应模型 / request-response models
    config.py            # 路径与配置 / paths and configuration
  data/
    kb/                  # 港航知识库 / maritime knowledge base
    evaluation/          # 固定检索与证据评测 / pinned retrieval and policy set
    public/              # 公开RL数据与血缘 / public RL data and provenance
    port_profiles/       # 可替换港口参数与边界 / swappable port profiles
    rl_datasets.json     # 数据集目录 / dataset registry
    xiaoyi_index.json    # 检索索引 / retrieval index
  scripts/
    build_index.py       # 构建知识索引 / build knowledge index
    fetch_public_rl_dataset.py # 下载并校验公开RL数据 / fetch and verify
    fetch_large_public_rl_dataset.py # 409,887行大规模基准 / large benchmark
    fetch_noaa_port_ais_dataset.py # NOAA港区AIS场景 / public port AIS
    run_rl_dataset_benchmark.py # 三数据集多种子RL证据 / multi-seed RL evidence
    run_rag_benchmark.py # 固定RAG基准与哈希报告 / benchmark and hash report
  web/
    index.html           # Web交互页面 / Web interface
  tests/
    test_retrieval.py    # 检索验证 / retrieval verification
    test_operations_api.py # 运营API与回归 / operations API and regression

推荐直接使用项目启动脚本；首次运行会创建 .venv、安装运行依赖、重建索引并启动服务：
Use the project launcher. On first run it creates .venv, installs runtime dependencies, rebuilds the index, and starts the service:

cd <xiaoyi-ai-repository>
bash run.sh

也可以手动运行：
Or run manually:

cd <xiaoyi-ai-repository>
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.lock
python scripts/build_index.py
uvicorn app.main:app --reload --port 8010

打开：
Open:

http://127.0.0.1:8010

cd <xiaoyi-ai-repository>
python -m app.cli "岸电 THDi 超标告警应该先检查什么？"
python -m app.cli "小懿的核心能力是什么？" --mode expert

小懿是面向港航场景的小型 AI 助手。它采用本地港航知识库和 RAG 检索，结合专业问答、SOP 生成、告警解释和运营建议。默认 local_rules 生成路径不依赖外部模型；也可显式配置 OpenAI-compatible 模型网关。只有已通过证据门禁、不含沙箱运营数据且完成外发授权的回答才允许发往外部模型；其他情况保留本地严格证据答案。

Xiaoyi is a compact AI assistant for maritime and port operations. It combines a local maritime knowledge base and RAG retrieval with professional Q&A, SOP generation, alert explanation, and operational guidance. The default local_rules path does not depend on an external model; an OpenAI-compatible gateway can be configured explicitly. Only answers that pass the evidence gate, contain no sandbox operational data, and receive outbound authorization may reach an external model; all other cases retain the local strict-evidence answer.

运营看板默认使用后端持续生成的运营沙箱事件流。它具有生产形态的业务对象、时间戳、质量码、延迟和来源适配器，但明确标记为非生产实绩。切换生产时保持 port-ops.v1 契约并配置只读数据网关；高风险任务仍返回 requires_human_confirmation: true，不会因接入真实数据自动获得写权限。

The operations dashboard consumes a continuously generated backend sandbox event stream. It uses production-shaped entities, timestamps, quality codes, latency, and source adapters while remaining explicitly labelled non-production. A live integration retains the port-ops.v1 contract and a read-only gateway. High-risk tasks still return requires_human_confirmation: true; real data never grants write authority automatically.

_{证据约束对话：现场数据未接入时明确拒绝生成运营实绩，同时保留自然语言研判、证据状态和人工确认入口。}

GET  /api/dashboard                 聚合概况、能耗、预警、任务 / aggregate operations, energy, alerts, tasks
GET  /api/runtime/status            模式、来源、质量与边界 / mode, provenance, quality, boundary
GET  /api/runtime/snapshot          船舶、泊位、设备等对象 / vessels, berths, equipment, yard, gates
GET  /api/operations/overview       运营概况 / operations overview
GET  /api/energy?range=today        能碳趋势 / energy-carbon trend (today / 7d / 30d)
GET  /api/alerts                    预警筛选 / alerts filtered by level/status
GET  /api/tasks/templates           任务模板 / executable task templates
POST /api/tasks                     创建沙箱任务 / create sandbox task
POST /api/tasks/{task_id}/next      推进任务步骤 / advance current step
POST /api/reports                   生成结构化报告 / generate structured report
GET  /api/reports/{report_id}       获取报告 / retrieve report
GET  /api/operator/scenarios        岗位问法与安全边界 / frontline prompts and safety limits

生产数据切换说明见 港口运营数据适配器。默认无需配置；接生产网关时设置 XIAOYI_PORT_DATA_MODE=live、XIAOYI_PORT_BASE_URL 和可选只读令牌即可。网关未返回 live_data_verified=true 或版本不是 port-ops.v1 时，服务会失败关闭，绝不把数据冒充生产实绩。

See the port-operations data adapter for live-data switching. No configuration is needed by default. For a production gateway, set XIAOYI_PORT_DATA_MODE=live, XIAOYI_PORT_BASE_URL, and an optional read-only token. The service fails closed unless the gateway returns live_data_verified=true and contract version port-ops.v1; unverified data is never presented as production performance.

运行测试：
Run tests:

python -m pip install -r requirements-dev.lock
pytest -q

本地模式仅用于回环开发。生产模式必须使用签名 JWT、显式主机名和 CORS 来源，否则服务拒绝启动。对话、任务、报告、自动化计划、反馈与审计保存在 SQLite；中断工作在重启后会安全标记为失败或取消，不会无声续跑。

Local mode is for loopback development only. Production requires signed JWTs, explicit hostnames, and CORS origins or the service refuses to start. Conversations, tasks, reports, automation plans, feedback, and audit evidence persist in SQLite. Interrupted work is safely marked failed or cancelled after restart rather than resuming silently.

GET  /health/live               进程存活 / process liveness
GET  /health/ready              深度就绪 / storage, index, RL, model, deployment readiness
GET  /metrics                   Prometheus指标 / metrics; restrict in production
GET  /api/system/info           安全与运维能力 / security and operations capability
GET  /api/models                模型、回退与熔断 / models, fallback, circuit breaker
GET  /api/conversations/{id}    持久对话 / identity-scoped conversation history
POST /api/chat/stream           SSE流式回答 / server-sent-event answer stream

部署、TLS/SSO、密钥、备份、模型数据外发和多实例边界见 部署指南；信任边界见 系统架构；开源审计结论见 真实性与工程化评估。

See the deployment guide for TLS/SSO, secrets, backups, model-data egress, and multi-instance boundaries; architecture for trust boundaries; and open-source readiness for the engineering audit.

完整分类问题库见：小懿可询问问题库。其中已区分当前运营沙箱、知识库问答和生产系统接入后实时问题。

See the categorized question library, which separates current sandbox questions, knowledge-base questions, and questions that require a verified live production connection.

RL板块不再回放其他项目的历史训练曲线。当前实现会在后台真实执行 Q-learning、SARSA、Expected SARSA 和 Double Q-learning，并用 PID 作为控制 理论基线。训练百分比来自已完成 episode 数，模型按算法保存并计算 SHA-256。

仓库同时保留三套数据：UCI Appliances 的 19,735 条原基准、UCI Household Power 聚合得到的 409,887 条五分钟级大规模基准，以及 NOAA Los Angeles–Long Beach 港区 710 个包含 AIS 消息的一分钟实测交通桶。前两套 证明算法规模与回归稳定性，不是港口实绩；AIS中的船舶数、航速、航行状态和 船型为公开观测，服务量、积压、等待和得分为校准沙箱代理。

The RL panel no longer replays historical curves from another project. It runs Q-learning, SARSA, Expected SARSA, and Double Q-learning in a real background worker, with PID as the control-theory baseline. Progress is derived from completed episodes; each algorithm artifact is saved and SHA-256 hashed.

The repository retains the original 19,735-row UCI benchmark, a 409,887-row five-minute UCI benchmark, and 710 observed minute buckets from public NOAA AIS messages in the Los Angeles–Long Beach port area. UCI data demonstrates algorithm scale, not port performance. AIS vessel count, speed, navigation status, and vessel class are measured; service, backlog, waiting, and score are calibrated sandbox proxies. Every dataset is split chronologically into train, validation, and sealed test segments. Training is headless and only post-training evaluation creates trajectories.

_{真实训练配置：三套公开数据、4 RL + PID、回合/时域/随机种子及训练无渲染、测试后回放边界均由后端接收。}

# 仓库已带数据；可从UCI重建 / bundled data; optionally rebuild from pinned UCI source
.venv/bin/python scripts/fetch_public_rl_dataset.py
.venv/bin/python scripts/fetch_large_public_rl_dataset.py
.venv/bin/python scripts/fetch_noaa_port_ais_dataset.py

# 复验固定三数据集×三种子报告 / verify the pinned multi-dataset report
.venv/bin/python scripts/run_rl_dataset_benchmark.py verify

# 运行全部测试 / run all tests
.venv/bin/python -m pytest -q

接口：

GET  /api/rl-lab/health
GET  /api/rl-lab/algorithms
GET  /api/rl-lab/datasets
GET  /api/rl-lab/contracts
GET  /api/rl-lab/evidence
POST /api/rl-lab/advisor
POST /api/rl-lab/runs
GET  /api/rl-lab/runs/{run_id}
POST /api/rl-lab/runs/{run_id}/cancel
POST /api/rl-lab/runs/{run_id}/evaluate

能源环境最少提供 timestamp,load_kw；港口作业环境最少提供 timestamp,vessel_count,anchored_vessels,avg_sog_knots，并设置 XIAOYI_RL_ENVIRONMENT_TYPE=port_operations 与港口 profile。字段名不同只需 配置 JSON 映射，不改训练器。完整说明见港口RL可替换数据契约 和落地执行清单。

The energy environment requires timestamp,load_kw. The port-operations environment requires timestamp,vessel_count,anchored_vessels,avg_sog_knots, XIAOYI_RL_ENVIRONMENT_TYPE=port_operations, and a port profile. Site columns are mapped through JSON without changing the trainer. See the swappable port RL contract and landing checklist.

_{港口环境契约：11项观测、5项动作、目标函数、硬约束、动作屏蔽和生产写入边界可直接与站点字段逐项核对。}

• 港口由哪些核心业务模块组成？ / What are the core operating domains of a port?
• 集装箱码头从船舶靠泊到离港的流程是什么？ / What is the container-terminal workflow from berthing to departure?
• TOS 系统在港口运营里负责什么？ / What does a TOS manage in port operations?
• 岸电 THDi 超标告警应该先检查什么？ / What should be checked first after a shore-power THDi alarm?
• 台风红色预警下港区要启动哪些安全流程？ / Which safety procedures apply under a red typhoon warning?
• 港口碳排放盘查需要保留哪些证据？ / What evidence must be retained for a port carbon inventory?
• 小懿的系统架构是什么？ / What is Xiaoyi’s system architecture?

项目已预留 TOS、PCS、EMS、EAM、VTS、AIS、气象海洋和国际贸易单一窗口连接器契约，但默认全部离线，未配置任何真实端点或凭据。安全配置、站点联调、写操作门禁、回滚和审计要求见 港口连接器接入手册，环境变量模板见 .env.connectors.example。

The project defines connector contracts for TOS, PCS, EMS, EAM, VTS, AIS, metocean services, and maritime single windows. All are offline by default, with no real endpoint or credential bundled. See the port-connector integration manual for secure configuration, site commissioning, write gates, rollback, and audit requirements, and .env.connectors.example for environment templates.

GET  /api/connectors                              目录与状态 / catalogue and status
GET  /api/connectors/{id}/field-mappings          字段映射 / field-mapping template
POST /api/connectors/{id}/health-check            真实健康探测 / real health probe
POST /api/connectors/{id}/write-preflight         写预检，不下发 / write preflight; no dispatch

POST /api/automation/plans                       自然语言转白名单步骤 / language-to-allowlisted steps
POST /api/automation/plans/{id}/next             回写并推进 / record result and advance
POST /api/automation/plans/{id}/confirm          人工确认或拒绝 / bind human approval or rejection
GET  /api/knowledge/status                       文档、来源与索引哈希 / docs, sources, index hashes
GET  /api/knowledge/catalog                      24类/96主题路线图 / 24-domain, 96-topic roadmap
GET  /api/knowledge/authority-coverage           权威覆盖与缺口 / authority coverage and gaps
POST /api/knowledge/search                       来源与双SHA-256检索 / search with source and dual hashes
GET  /api/knowledge/sources                      来源登记与等级 / source registry and verification level
POST /api/knowledge/intake                       待审资料暂存 / stage material for human review

专业资料全目录与当前覆盖状态见 港航专业知识总目录；知识来源分级、资料审核、发布、索引重建与拒答边界见 知识库治理说明。

一线调度、值班、设备、闸口、堆场和交接班人员的完整使用流程见 一线操作人员系统指南。

See the maritime knowledge catalogue for current coverage and the knowledge-governance guide for source tiers, review, publication, index rebuilds, and refusal boundaries. The frontline operator guide covers dispatchers, duty teams, equipment, gates, yard personnel, and shift handover.

小懿只承担港航知识、RAG、上下文识别、能力路由、结果解释和审计，不复制能碳驾驶舱、数字孪生平台、马六甲沙盘或航行模拟器的业务功能。跨系统能力默认 offline，不访问其他系统；dry-run 只检查契约，显式配置为 live 后也只允许登记的 GET 只读能力。

Xiaoyi owns maritime knowledge, RAG, context resolution, capability routing, result explanation, and audit. It does not duplicate the CarbonOps cockpit, digital-twin platform, Malacca sandbox, or sailing simulator. Cross-system capabilities default to offline; dry-run verifies only contracts, and even explicit live mode permits registered read-only GET capabilities only.

_{联动与评测闭环：7/7代表小懿平台能力已登记；标题同步给出4个系统与11项只读能力边界，并展示知识快照、检索对照、证据策略和持久审计。}

GET  /api/hub/systems                            四系统目录 / four-system catalogue
GET  /api/hub/capabilities                       只读能力 / read-only capabilities
POST /api/hub/capabilities/{id}/invoke           隔离预览或授权只读 / isolated preview or approved read
POST /api/context/resolve                        统一业务上下文 / unified business context
POST /api/evidence/fuse                          证据融合 / knowledge-system-simulation fusion
POST /api/orchestrator/run                       跨系统编排 / natural-language orchestration
GET  /api/governance/audit                       SQLite持久审计 / persistent audit
POST /api/evaluation/run                         固定RAG回归 / pinned RAG regression
POST /api/evaluation/feedback                    人工反馈 / human feedback
POST /api/evaluation/feedback/{id}/review        审核入待审区 / reviewed intake staging

网页左侧点击“智能联动中心”即可查看 7/7 完成度、系统能力注册表、跨系统安全预览、RAG 评测和反馈闭环。完整验证步骤见 智能联动中心说明。

Open “智能联动中心 / Intelligence Hub” from the left navigation to inspect 7/7 capability status, the system registry, safe cross-system previews, RAG evaluation, and the feedback loop. See the intelligence-hub guide for verification.

仓库提供 60 题固定版本评测集：40 题检索、20 题证据策略；其中 35 题构成 v1 固定测试分区。当前知识快照为 112 份文档、708 个分块和 60 份官方核验来源。测试分区的 24 个检索题上，Hybrid Sparse 的 Hit@1/3/5 为 87.50%/100%/100%，BM25-only 为 75.00%/95.83%/100%；Hybrid 在首位命中率上提升 12.50 个百分点， MRR 为 0.9236 对 0.8507（+7.29 个百分点）。Hit@5 同为 100%，不把 已经饱和的 Top-5 指标包装成提升。 11 个策略测试覆盖条款级拒答、无依据回答阻断、辖区路由、法规日期切换和 实时数据边界，当前为 11/11。

The repository publishes a fixed 60-question set: 40 retrieval cases and 20 evidence-policy cases, with 35 forming the pinned v1 test partition. The knowledge snapshot contains 112 documents, 708 chunks, and 60 officially verified sources. Across the 24 retrieval questions in the test partition, Hybrid Sparse reaches Hit@1/3/5 of 87.50%/100%/100%, versus 75.00%/95.83%/100% for BM25-only. Hybrid improves first-rank hit rate by 12.50 percentage points and MRR from 0.8507 to 0.9236 (+7.29 percentage points). Since both methods already reach 100% Hit@5, the README does not misrepresent the saturated Top-5 metric as an improvement. Eleven policy tests cover clause-level refusal, unsupported-answer blocking, jurisdiction routing, regulation-date switching, and live-data boundaries; all 11 pass.

# 快速哈希核验 / verify report-bound data, index, and policy-code hashes
.venv/bin/python scripts/run_rag_benchmark.py verify

# 深度复算60题 / rerun all 60 cases; may take minutes on one CPU core
.venv/bin/python scripts/run_rag_benchmark.py verify --deep

# 重新生成报告 / regenerate the report
.venv/bin/python scripts/run_rag_benchmark.py run

固定题集、JSON证据报告和 可读报告随仓库发布。该测试分区用于 v1 发布验收，并在工程修复中暴露过缺陷，因此不是“从未查看的独立留出集”； 题目由项目维护，也不是第三方用户研究。上述数字是仓库基准上的检索与安全 指标，不是港口生产收益、全球知识覆盖率、法律意见或线上 SLA。

The fixed questions, JSON evidence report, and readable report ship with the repository. The partition is a v1 release-acceptance set that has exposed defects during engineering fixes; it is not a never-inspected independent holdout, and it is maintained by this project rather than a third-party user study. These are repository retrieval and safety metrics—not port-production benefits, global knowledge coverage, legal advice, or an online SLA.

简历可用声明与禁用表述见 简历指标口径。
See resume claim semantics for permitted and prohibited wording.