RAGSpine 用法 & Dify 流程迁移手册

ragspine quickstart                 # 10 秒离线演示:一个命中(带来源) + 一个诚实"查不到"
ragspine ask --db data/fact_metric.db "中国内地FY2024的REVENUE是多少"

from ragspine.storage.fact_store import Fact, FactStore
from ragspine.agent.llm_provider import MockProvider
from ragspine.agent.agent import answer_question

# 1. 事实库(:memory: 临时;传路径就是真 sqlite)
store = FactStore(":memory:"); store.init_schema()

# 2. 一条事实 —— 最后两个字段是它的"血缘"(来自哪个文档、文档里哪个位置)
store.upsert_facts([Fact(
    metric_code="REVENUE", entity="ACME_CN", geography="CN", channel="TOTAL",
    period_type="FY", period="2024", value=1320.0, unit="USD_M",
    source_doc_id="ACME_FY2024_Results.pptx", source_locator="slide=6,table=1,row=2,col=3",
    tags={}, dimensions={},
)])

# 3. 离线确定性 provider(无 key、无网络);上线换 AnthropicProvider 即可
provider = MockProvider()

# 4. 提问。命中 → 带来源回答;缺失 → 诚实拒答,绝不编造
result = answer_question("中国内地FY2024的REVENUE是多少", store, provider)
print(result.answer)    # 确定值 + 来源,或诚实的"查不到"
print(result.sources)   # [{'doc':..., 'locator':...}]

RAGSPINE_DB_PATH=data/fact_metric.db python scripts/run_server.py --port 8000   # FastAPI
python scripts/run_worker.py                                                     # RQ worker(需 Redis)

中国内地FY2024的REVENUE是多少，为什么会有这样的变化   → composite ✅
中国内地FY2024的营收是多少                          → structured(只有指标,没叙事词)
中国内地业绩为什么下滑                               → narrative(只有叙事词,没指标)

from ragspine.retrieval.chunking.chunking import DocumentMeta, chunk_document
from ragspine.retrieval.chunking.chunk_store import ChunkStore

meta = DocumentMeta(doc_id=..., title=..., entity=..., geography=..., period=...,
                    language="zh", sensitivity="INTERNAL",   # 切勿用 RESTRICTED,会被检索出口剔除
                    source_locator_prefix=...)
chunks = chunk_document(text, meta)          # 段落贪心切块,每块自带 source_locator
ChunkStore(db).replace_doc_chunks(doc_id, chunks, valid_as_of="2025-03-31")  # 幂等版本化写入

"""RAGSpine composite 路由端到端最小示例(纯 Python,离线,无 key)。"""
import tempfile
from datetime import date
from pathlib import Path

from ragspine.agent.agent import answer_question
from ragspine.agent.llm_provider import MockProvider
from ragspine.retrieval.chunking.chunking import DocumentMeta, chunk_document
from ragspine.retrieval.chunking.chunk_store import ChunkStore
from ragspine.retrieval.link.narrative_link import build_narrative_retriever
from ragspine.storage.fact_store import Fact, FactStore

tmp = Path(tempfile.mkdtemp(prefix="ragspine_demo_"))
fact_db, chunk_db = tmp / "facts.db", tmp / "chunks.db"

# a. 数字侧:写一条事实。注意 Fact 字段全部必填(tags/dimensions 也要显式传 {})
fact_store = FactStore(fact_db); fact_store.init_schema()
fact_store.upsert_facts([Fact(
    metric_code="REVENUE", entity="ACME_CN", geography="CN", channel="TOTAL",
    period_type="FY", period="2024",            # 注意是 "2024" 不是 "FY2024"
    value=128.6, unit="亿元",
    source_doc_id="FY2024_annual_report.pptx", source_locator="p.12",
    tags={}, dimensions={},
)])

# b. 叙事侧:切块灌入归因文本(带来源)
doc_id = "FY2024_mdna.pptx"
meta = DocumentMeta(doc_id=doc_id, title="FY2024 中国内地业务经营回顾",
                    entity="ACME_CN", geography="CN", period="2024", language="zh",
                    sensitivity="INTERNAL", source_locator_prefix=doc_id)
text = ("FY2024 中国内地营收同比增长主要由三方面驱动:\n"
        "一是代理人渠道产能提升,活动率与人均件数双升;\n"
        "二是银保渠道与头部银行的独家合作贡献了新增长极;\n"
        "三是续期业务因前期高质量新单而保持高留存。")
cs = ChunkStore(chunk_db); cs.init_schema()
cs.replace_doc_chunks(doc_id, chunk_document(text, meta), valid_as_of="2025-03-31")
cs.close()                                      # 写完即关,检索时重开同一个库

# c. 构造检索器(默认纯 BM25+RRF;传 provider 才挂 LLM 二审)
retriever, ret_store = build_narrative_retriever(chunk_db, provider=None)

# d. 提一个 composite 问题(既问数字又问归因)
provider = MockProvider(reference_date=date(2026, 6, 22))
result = answer_question(
    "中国内地FY2024的REVENUE是多少,为什么会有这样的变化",
    fact_store, provider,
    reference_date=date(2026, 6, 22),
    narrative_retriever=retriever,
)

print("route   :", result.route)
print("answer  :\n" + result.answer)
print("sources :", result.sources)
ret_store.close(); fact_store.close()

route   : composite
answer  :
ACME_CN FY2024 REVENUE：128.6 亿元(来源：FY2024_annual_report.pptx · p.12)

归因分析:
基于检索到的资料: …(检索到的归因片段,带来源)
sources : [{'doc':'FY2024_annual_report.pptx','locator':'p.12'},
           {'doc':'FY2024_mdna.pptx','locator':'FY2024_mdna.pptx#para1-4'}]

from ragspine.agent.llm_provider import AnthropicProvider
provider = AnthropicProvider(model="claude-...", base_url="https://你的企业网关")  # 需装 [llm] extra
# 其余代码不变:answer_question(question, fact_store, provider, narrative_retriever=retriever)