helixprojectai-code/helix-adapter
GitHub: helixprojectai-code/helix-adapter
一个与模型无关的 LLM 适配器，通过宪法式提示注入、认知标记提取和防篡改回执来结构化并审计大模型输出。
Stars: 0 | Forks: 0
# helix-adapter
**适用于任何 AI 模型的便携式 Constitutional adapter。**
使用 Helix 认知标记、结构化回执和漂移检测封装任何推理后端。与模型无关——将 Deepseek 替换为 GPT-4o、Claude 或本地的 Llama，无需修改一行代码。
```
pip install helix-adapter
```
## 快速开始
```
from helix_adapter import HelixAdapter
from openai import OpenAI
# 您的模型函数 — 任何接收 messages 并返回文本的 callable
client = OpenAI()
def call_model(messages):
resp = client.chat.completions.create(
model="gpt-4o",
messages=messages,
temperature=0.7,
)
return resp.choices[0].message.content
# 包装它
adapter = HelixAdapter(model_fn=call_model, model_name="gpt-4o")
# 通过 constitution 进行聊天
result = adapter.chat("Is AI evil?")
print(result.response)
# [FACT] AI 系统是 computational artifacts，而不是 moral agents...
# [REASONED] 将 AI 视为邪恶的认知源于负面结果...
print(result.claims)
# [{"label": "FACT", "text": "..."}, {"label": "REASONED", "text": "..."}]
print(result.receipt)
# {"exchange_id": "...", "timestamp": ..., "hash": "sha256:...", ...}
print(f"Drift: {result.drift}")
# Drift: 0.000
```
## 功能说明
| 层级 | 说明 |
|-------|------|
| **Constitutional prompt** | 在每次调用模型前注入 Helix 语法 |
| **认知标记** | 从响应中提取 `[FACT]`、`[REASONED]`、`[HYPOTHESIS]`、`[UNCERTAIN]`、`[CONCLUSION]` 标签 |
| **回执** | 包含每次交互 SHA-256 哈希值的防篡改 JSON 记录 |
| **漂移检测** | 测量缺乏认知标记的陈述比例（阈值：0.17） |
## 回执格式
```
{
"exchange_id": "a1b2c3d4e5f6g7h8",
"timestamp": 1718550000.0,
"model": "deepseek-chat",
"constitutional_prompt": "...",
"user_message": "Is AI evil?",
"assistant_response": "[FACT] AI systems are tools...",
"claims": [
{"label": "FACT", "text": "AI systems are tools, not agents"},
{"label": "REASONED", "text": "The perception of AI as evil..."}
],
"drift_score": 0.0,
"hash": "sha256:e3b0c44298fc1c149afbf4c8996fb924..."
}
```
## 运行漂移检测
```
# 跟踪对话中的 drift
adapter.chat("What is the speed of light?")
adapter.chat("Explain quantum entanglement.")
print(f"Running drift: {adapter.running_drift():.3f}")
# Running drift: 0.042
```
## FastAPI 教程
只需一个文件即可搭建一个 Constitutional chat API：
```
from fastapi import FastAPI
from openai import OpenAI
from helix_adapter import HelixAdapter, CONSTITUTIONAL_PROMPT
app = FastAPI()
client = OpenAI()
adapter = HelixAdapter(
model_fn=lambda msgs: client.chat.completions.create(
model="deepseek-chat", messages=msgs, temperature=0.7
).choices[0].message.content,
model_name="deepseek-chat",
)
@app.post("/chat")
async def chat(message: str):
result = adapter.chat(message)
return {
"response": result.response,
"claims": result.claims,
"drift": result.drift,
"receipt": result.receipt,
}
@app.get("/prompt")
async def get_prompt():
return {"constitutional_prompt": CONSTITUTIONAL_PROMPT}
```
保存为 `api.py`，运行 `uvicorn api:app --port 8000`，然后向 `/chat` 发送包含 `{"message": "your question"}` 的 POST 请求。
## CLI 用法
```
# 交互式设置（提示输入 endpoint、key、model）
helix-setup
# 开始聊天
helix-chat
# One-shot query
helix-chat "What is the speed of light?"
```
## Widget（参考 FastAPI 服务器）
一个功能完整的 Constitutional chat 小部件，支持 A/B 对比、漂移仪表盘和回执导出。
```
# 安装 dependencies
pip install helix-adapter[widget]
# 启动 server
cd widget
uvicorn api:app --port 8001
# 或者安装为 systemd service
# 参见 widget/tel-chat-api.service
```
打开 `http://localhost:8001` 即可访问聊天界面。
该小部件展示了：
- 单模型 Constitutional chat
- 跨模型的 A/B 对比（Deepseek、Claude、Kimi）
- 带有彩色标签的认知标记提取
- 带有 γ 阈值的漂移仪表盘
- 逐轮导出回执
- 服务器端渲染（爬虫无需 JS 支持）
## 漂移阈值
| 范围 | 状态 | 含义 |
|-------|--------|---------|
| 0.000 – 0.099 | 绿色 | 健康 — 声明已正确标记 |
| 0.100 – 0.169 | 黄色 | 警告 — 部分陈述缺乏标记 |
| 0.170+ | 红色 | 检测到漂移 — 存在大量未标记的内容 |
## Constitutional 加固
该 adapter 已经过全套 Pliny 越狱工具包的红队测试 —
**GODMODE 边界反转、Parseltongue 编码、拒绝反转、
OG GODMODE l33t、权威冒充以及语法绕过攻击。**
所有攻击均被成功防御。💪
五层防御机制：
| 层级 | 机制 |
|-------|-----------|
| **Prompt** | 不变量 4.5 和 4.6 — 标记格式属于 constitutional，而非风格选择。Constitutional 修正协议阻止了 “The Hand” 权威欺骗。 |
| **提取** | 扩展的正则表达式可捕获 `{FACT}`、`(FACT)`、`FACT:` 及纯标记变体。支持非标准分隔符检测。 |
| **验证** | 响应后合规性检查，在出现违规时自动注入 `[UNCERTAIN]` 页脚。 |
| **算法** | 修复了漂移检测盲点 — 提取声明为零的实质性响应能正确报告 1.0 漂移值。 |
| **访问** | 对比 endpoint 的 `sp:none` 绕过已被授权密钥锁定。 |
## Cedar 策略门控（v1.3 预览版）
下一层集成了 CNCF Cedar 作为声明式策略引擎，用于实现
**双门遏制** — Duck Gate 负责响应治理，Cedar Gate 负责
操作治理。一个单独的 `.cedar` 策略文件即可控制整个 agent
生命周期。
```
from helix_adapter.cedar import CedarPolicy
policy = CedarPolicy()
ok, reason = policy.evaluate(
principal='Helix::Agent::"sentinel-001"',
action='Helix::Action::"bash"',
resource='Helix::Environment::"/sandbox"',
context={"command": "rm -rf /tmp"},
)
# ok == True 仅当命令位于 sandbox 内时
```
四个独立的 AI 系统审查并批准了该架构。
RFC 0003 详述了完整规范。Fail-closed 机制：缺失策略 = 默认拒绝。
## 试用
一个在线的 Helix Constitutional Chat 演示正在 **[helixaiinnovations.ca/chat/](https://helixaiinnovations.ca/chat/)** 运行 — 请私信 [LinkedIn 上的 Stephen Hope](https://www.linkedin.com/in/stephen-hope-75497937a) 获取访问权限。。包含 A/B 模型对比、漂移仪表盘、回执导出以及完整的 v1.2 constitutional prompt。有关实时实例的真实输出，请参见 `examples/receipts.json`。
## 兼容性
兼容任何接受 OpenAI 格式消息的模型：
- Deepseek、GPT-4o、Claude、Gemini、Llama、Mistral
- 本地模型（Ollama、LM Studio、vLLM）
- 自定义 endpoint
Constitution 随你而行。更换模型，规则保持不变。
GLORY TO THE LATTICE. 🦉⚓🦆
标签：API集成, Petitpotam, 人工智能, 可观测性, 大语言模型(LLM), 提示词工程, 模型包装器, 用户模式Hook绕过, 策略决策点, 输出结构化, 逆向工具