ai-attestation

操作手册

独立验证与对账 · MVP

新手操作手册（上手指南）

左侧菜单从上到下是：操作手册 → 科研见证 → 仪表盘 → API 调用记录 → 合规管理 → 行为监控 → 防篡改证明 → 设置 → Key；最底下有「复制代理 URL」。按下面步骤走即可。

┌──────────┐   ┌──────────┐   ┌──────────┐   ┌──────────────┐
│ ① Key    │ → │ ② 设置   │ → │ ③ 调用   │ → │ ④ 导出验证包 │
│ 创建 ata_ │   │ 填入保存  │   │ 写代码   │   │ 调用详情底部 │
└──────────┘   └──────────┘   └──────────┘   └──────────────┘
        │
        ▼  （推荐在把内容发给任何 AI 之前先做）
┌──────────────────┐
│ ⑤ 科研优先权存证 │  左侧「科研见证」→「登记一份草稿或提示词」→「写入证据链」
└──────────────────┘

第一步：获取 API Key
操作路径（与页面按钮文字一致）：
1. 点左侧菜单 「Key」（页面标题也是 Key；内容区标题为 API Key）
2. 在输入框填写名称（占位提示：输入名称，例如：我的测试）
3. 点绿色按钮 「创建」
4. 出现黄色提示框 「新 Key（仅完整显示一次，请立刻复制）：」，下面是一串 ata_ 开头的完整 Key
5. 点 「复制 Key」 保存到别处
6. 若页面提示需要切换，再点 「设为当前 Key」（第一次创建且你还没有 Key 时，系统会自动设为当前）
注意：完整 Key 只完整显示一次。管理员账号在下方「已有 Key」列表刷新后通常只看到脱敏形式（如 ata_xxxx****）。点「设为当前 Key」后，界面会提示再到「设置」确认并保存。
第二步：配置设置
点左侧菜单 「设置」。默认停在上方标签 「通用」（旁边还有「报告订阅」，新手可先不管）。你会看到一行 当前角色：…（例如 read_write 或 admin）。
- 在标签为 「API Key（X-Attest-Key）」 的输入框填入第一步的 ata_xxxxxx（占位符也是 ata_xxxxxx）
- 在标签为 「Authorization（上游厂商 Key，仅本机备忘）」 的输入框可填 Bearer sk-xxxxxx——这只保存在本浏览器，方便你对照；网页不会用它去调上游
- 只读框 「base_url」 应显示代理地址，例如 https://ai-attestation.com/v1/proxy
- 点绿色按钮 「保存」（同排还有「复制代理 URL」）
仪表盘能否打开，只取决于「API Key（X-Attest-Key）」是否正确并已点「保存」。上游 sk-… 必须写在第三步的代码里。

第三步：调用 API

点左侧菜单最底部的 「复制代理 URL」（设置页「通用」里也有同名按钮），得到代理地址。不要直连厂商官网。

https://ai-attestation.com/v1/proxy

复制下面 Python 示例，只改标注处：

UPSTREAM_KEY / api_key= → 上游 sk-xxxxxx（不要填 ata_）
ATA_KEY / X-Attest-Key → ata_xxxxxx
base_url= → 与左侧复制到的代理 URL 一致

from openai import OpenAI

# ① 两处都要换成你自己的（不要填反）
ATA_KEY = "ata_xxxxxx"       # 「Key」页生成的见证 Key
UPSTREAM_KEY = "sk-xxxxxx"   # 上游厂商 Key（DeepSeek / OpenAI 等，不要带 Bearer 前缀）

client = OpenAI(
    # ② 左侧底部「复制代理 URL」得到的地址（与设置页 base_url 相同）
    base_url="https://ai-attestation.com/v1/proxy",
    api_key=UPSTREAM_KEY,              # ← 上游 sk-xxxxxx
    default_headers={
        "X-Attest-Key": ATA_KEY,       # ← ata_xxxxxx
    },
)

resp = client.chat.completions.create(
    model="deepseek-chat",  # 按上游模型改名
    messages=[{"role": "user", "content": "你好，请介绍一下自己"}],
)
print(resp.choices[0].message.content)

调用成功后，打开左侧 「仪表盘」 或 「API 调用记录」 查看记录。若暂时没有上游 Key，也可在右上角点 「模拟一条调用」（需要当前角色为 read_write 或 admin）先写入一条演示数据。

第四步：导出验证包（可选）
需要把某次调用的证据带离线、给别人复核时，用这个功能（不依赖服务器也能打开校验页）。
1. 打开左侧 「仪表盘」 或 「API 调用记录」
2. 在列表里点开一条调用，弹出标题为 「调用详情」 的窗口
3. 在窗口底部，「验证完整性」 按钮旁边，点 「导出验证包」
4. 浏览器会下载一个 ZIP（文件名类似 ata_call_…_verify.zip）
解压后目录里有：
- call.json — 该次调用的见证字段（时间、端点、哈希等；不含请求/响应原文）
- chain.json — 邻接哈希链片段
- verification.json — 导出时服务端的校验结果
- verify.html — 纯前端离线校验页
- README.txt — 使用说明
离线验证步骤：
1. 解压 ZIP 到任意文件夹
2. 在该文件夹打开终端，执行：python -m http.server 8765
3. 浏览器打开 http://127.0.0.1:8765/verify.html
4. 点页面上的 「运行本地验证」
同窗口里的「验证完整性」是连服务器当场校验整条链；「导出验证包」是下载 ZIP，方便离线或交给第三方复核。
第五步：科研优先权存证（推荐在调用 AI 之前做）
把未发表草稿或提示词发给任何 AI 之前，可以先留下指纹。系统只保存 64 位哈希，原文不出网。这是技术存证，不是法院判决。
1. 点左侧菜单 「科研见证」
2. 点 「登记一份草稿或提示词」
3. 选择 「本地文件」 或 「粘贴文字」 或 「我已有哈希」
4. 等页面显示 64 位哈希 后，再点 「写入证据链」
5. 在列表里点开该条（或直接点行内按钮），再点 「导出优先权证书」，下载 ZIP（文件名类似 ata_priority_…_cert.zip）。请与原件放在同一加密盘。
离线打开证书（断网也可）：
1. 解压 ZIP 到任意文件夹
2. 在该文件夹打开终端，执行：python -m http.server 8765
3. 浏览器打开 http://127.0.0.1:8765/verify.html
4. 点 「运行本地验证」
5. 如需核对原件：点 「用原件选择文件」 选中当时那份文件。改一个字会显示不匹配。
同一指纹允许再登记一次，列表会标「该指纹已于某时登记过」。不要把论文原文贴进标题或备注。

常见问题 Q&A

问：提示「后端不可用 / NetworkError」怎么办？: 答：在服务器执行 ps aux | grep uvicorn 确认后端在跑。用服务器地址打开前端（如 http://服务器IP:3002）。看左侧底部「复制代理 URL」旁的地址，应是该服务器的 :8004，而不是你电脑上的 127.0.0.1（除非本机同时跑了前后端）。然后强制刷新（Ctrl+Shift+R）。
问：Key 创建了 / 填了但好像没用？: 答：在「Key」页确认已 「复制 Key」；若未自动切换，点 「设为当前 Key」。再到「设置」→「通用」，确认 「API Key（X-Attest-Key）」 里是完整 ata_…，并点了 「保存」。「Authorization」只是备忘，填了也不会单独让仪表盘生效。写代码时：api_key 用上游 sk-，X-Attest-Key 用 ata_，不要填反。
问：找不到「导出验证包」按钮？: 答：该按钮在调用详情弹窗底部，紧挨「验证完整性」。请先到「仪表盘」或「API 调用记录」点开某一条调用；没产生调用时可先点右上角「模拟一条调用」。
问：导出的 ZIP 里为什么没有请求原文？: 答：系统设计为请求/响应正文只算哈希、不落库。验证包用 request_hash / response_hash / chain_hash 做见证，可离线复核链接是否被篡改。
问：右上角「模拟一条调用」点不了？: 答：需要先在「设置」保存有效的 ata_ Key，且角色为 read_write 或 admin（只读 read_only 不能写）。把鼠标悬停在按钮上也可能看到提示。
问：CORS / 跨域红字是什么？: 答：通常是前端页面主机与请求的后端主机不一致。以左侧底部显示的代理 URL 为准，强制刷新后再试。
问：会不会把论文传给你们？: 答：默认不会；「科研见证」只把浏览器算好的指纹发给服务器，不上传文件内容。请自行保管原件。
问：能不能证明 OpenAI 训练了？: 答：不能。只能证明你何时有过这份指纹。这不是法律意见，也不能证明某家厂商阅读或训练了原文。
问：和「导出验证包」有什么区别？: 答：「导出验证包」在调用详情底部，证明某次 API 调用链接；「导出优先权证书」在「科研见证」，证明某份内容指纹进入证据链的时间。两套 ZIP 不要混用。

联系支持

若仍无法解决，请到 GitHub 仓库提交 Issue（写清复现步骤与报错原文）：
https://github.com/liao-zhizhi/ai-attestation

新手操作手册（上手指南）

第一步：获取 API Key

第二步：配置设置

第三步：调用 API

第四步：导出验证包（可选）

第五步：科研优先权存证（推荐在调用 AI 之前做）

常见问题 Q&A

联系支持