手把手：怎么把幻觉检测 API 接进你的 AI 应用？

网页粘贴检测适合人工抽查，但一旦你的 AI 应用日活上来，靠人盯不现实——得把幻觉检测接进流水线，让每一条高风险输出自动过一遍。这篇讲清楚接入的通用模式。

0. 什么样的场景值得接 API

不是所有输出都要检。按风险分级接，成本最划算：

• 高后果场景必接：医疗、法律、金融、政务——输出影响决策或对外声明。
• 批量场景接 API：客服回复、知识库问答、RAG 摘要，量大且重复。
• 低风险场景抽查：闲聊、内部草稿，人工抽检即可。

下面是按风险分级接入的决策流程：

1. 接入三步走

第 1 步：拿 API Key。 在官网 aihcc.cloud 开通 API 版（约 0.1 元/次调用），拿到密钥。把密钥放环境变量，别硬编码进仓库。

# .env
HALLUCC_API_KEY=sk-your-key-here

第 2 步：发请求。 核心就是把待检测文本发过去。下面是通用接入示意，具体接口字段以官方文档为准（endpoint、入参出参名仅作占位演示）：

# detect.py（示意，接口规格以官方文档为准）
import os, requests

HALLUCC_API_KEY = os.getenv("HALLUCC_API_KEY")
HALLUCC_ENDPOINT = "https://<官方域名>/v1/detect"   # 占位，以文档为准

def detect(text: str, domain: str = "通用") -> dict:
    resp = requests.post(
        HALLUCC_ENDPOINT,
        headers={"Authorization": f"Bearer {HALLUCC_API_KEY}"},
        json={"text": text, "domain": domain},
        timeout=30,
    )
    resp.raise_for_status()
    return resp.json()

# 等价 curl 示意
curl -X POST https://<官方域名>/v1/detect \
  -H "Authorization: Bearer $HALLUCC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"某条待检测的 AI 输出","domain":"通用"}'

第 3 步：解析四色结果。 返回的核心是「把文本拆成声明 + 每条声明的置信度」。HallucC 用 6 档置信度映射到 4 色——绿色=有可靠来源支撑，黄色=基本可信但不够权威，橙色=存疑，红色=高概率幻觉。拿到结果后，业务侧通常只关心红橙两档：

# 结果解析示意（字段名以官方文档为准）
def filter_risky(result: dict):
    claims = result.get("claims", [])
    return [c for c in claims if c.get("color") in ("red", "orange")]

risky = filter_risky(detect(agent_reply))
if risky:
    # 触发人工复核 / 拦截 / 打回重生成
    escalate_to_human(risky)

整体接入链路如下：

2. 上线前的几个工程细节

• 领域参数要传对：HallucC 支持 6 个领域（通用/医疗/法律/金融/教育/政务），不同领域挂不同的可信源配置，传错了检出率会掉。
• 超时与降级：检测服务挂了别把主业务也拖死，给个降级策略（放行 + 打标记事后补检）。
• 成本控制：约 0.1 元/次，按风险分级调用比全量调用省得多——只在「高后果 + 批量」节点接。
• 结果回流：红橙声明归档成测试集，反向丰富你的提示词规则库。

上线前的工程细节可以串成一条链路：

3. 一句话总结

接入本身不难——就是「发文本、收四色、拦红橙」三步。难的是把它接在正确的位置（高风险输出节点）并配上降级与成本策略。想跑通流程，可以先拿网页版（粘贴文本即可，零代码）验证检出效果，再上 API 自动化，官网 aihcc.cloud 上都有入口。