实用提示：OKF与RAG——终极AI智能体

本指南将逐步构建从原材料到可运行系统的完整流程，适用于“OKF + RAG：终极AI智能体架构”。重点在于可操作的步骤、明确的检查点，以及可直接放入代码仓库的代码，无需猜测其用途。在修改代码之前，应先明确输入参数、各步骤的负责人以及完成标准。操作人员应能够从已知的检查点重新运行相应步骤，而无需推测隐藏状态。应将此阶段视为输入与经过验证的输出之间的契约：为生成物命名、定义成功标准，杜绝默许的半完成状态。

两种记忆系统

在研究“两种记忆系统”时，首先写下相关约定：所需输入、成功信号以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改保持一致性。 在功能结果旁记录执行时间以及令牌或查询成本。提前了解成本情况，可避免从演示环境过渡到共享环境时出现意外费用。 在调整提示词之前，先用固定的问题集测试召回率。仅仅更换提示词很难改善较差的检索效果。

什么是OKF？（开放知识格式）

在研究“什么是OKF？（开放知识格式）”时，首先需列出相关规范：所需的输入参数、成功标志以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改始终符合要求。 应将配置信息与应用程序代码分开。环境文件、密钥存储以及功能开关应集中存放于一处，这样操作人员无需查看整个系统结构即可进行审计。 在调整提示词之前，需先使用固定的问题集来测试召回率。仅仅更换提示词往往无法改善较差的检索效果。

---
type: metric
title: "Monthly Churn Rate"
description: "Official formula for calculating monthly customer churn."
owner: "data-engineering"
tags: [revenue, kpi, board-report]
timestamp: 2026-06-20T10:00:00Z
---

# Monthly Churn Rate

The official churn rate formula used in all board reports and investor decks:

    Churn Rate = (Customers Lost During Month / Customers at Start of Month) × 100

### Rules
- **Do NOT** use trial accounts in the denominator.
- **Do NOT** count plan downgrades as churn.
- Source of truth: `analytics.monthly_churn_summary` table.

### Related
- [Monthly Active Users](mau.md)
- [Revenue Dashboard](revenue_dashboard.md)

为何这很重要

在分析“为何这很重要”时，首先需列出相关约定：所需输入、成功标志以及部分失败时的处理方式。这样的清单能确保后续的代码修改保持一致性。 同时记录正常流程与异常恢复路径。重试机制、人工审核环节以及错误消息处理都是产品功能的一部分，而非后续的优化工作。 在调整提示词之前，先使用固定的问题集来衡量检索效果。仅仅更换提示词很难解决检索能力不足的问题。 在分析“为何这很重要”时，首先需列出相关约定：所需输入、成功标志以及部分失败时的处理方式。这样的清单能确保后续的代码修改保持一致性。 将此阶段视为输入与经过验证的输出之间的契约。为相关成果命名，明确成功标准，杜绝无声的半完成状态。

什么是RAG？（检索增强生成）

RAG（检索增强生成）作为一种可度量的体系来设计时效果最佳。在扩大应用范围之前，先记录一个成功的案例、一个失败案例以及回滚说明。在功能结果旁还需标注处理时间以及令牌或查询成本。提前了解这些成本，就能避免在系统从演示环境过渡到共享环境时出现意外费用。应将分块策略与检索策略分开，当质量指标发生变化时，修改其中一项不应迫使重新编写另一项。

混合架构：OKF + RAG

混合架构：将OKF与RAG视为可度量的整体时效果最佳。在扩大范围之前，先记录一份优秀的处理结果、一个失败案例以及回滚说明。 将配置置于应用程序代码之外。环境文件、密钥存储和功能开关应集中存放，以便操作人员无需查看整个系统结构即可进行审计。 将分块策略与检索策略分开。当质量指标发生变化时，修改其中一项不应迫使重新编写另一项。

路由器如何决策

将“路由器如何决策”视为可测量的对象来处理最为有效。在扩大范围之前，先记录一个成功的案例、一个失败案例以及回滚说明。同时记录正常流程和恢复流程。重试机制、人工审核环节以及死信处理都是产品本身的一部分，而非后续需要补充的内容。应将分块策略与检索策略分开，当质量指标发生变化时，修改其中一项不应迫使重新编写另一项。

实现示例

将实现示例视为可度量的对象时效果最佳。在扩大范围之前，先记录一个成功的案例、一个失败案例以及回滚说明。 优先选择小型且可测试的单元，而非庞大的脚本。当某个步骤失败时，故障应指向单一责任模块，而非复杂的流程链。 将分块策略与检索策略分开。当质量指标发生变化时，修改其中一项不应迫使重新编写另一项。

from openai import OpenAI
import os
import glob
import yaml

client = OpenAI()

# 1. Load the OKF knowledge bundle from the local directory
def load_okf_bundle(bundle_path: str) -> dict:
    """Reads all Markdown files in the OKF directory into a searchable dict."""
    knowledge = {}
    for filepath in glob.glob(f"{bundle_path}/**/*.md", recursive=True):
        with open(filepath) as f:
            content = f.read()
            # Extract the title from YAML frontmatter
            if content.startswith("---"):
                _, frontmatter, body = content.split("---", 2)
                meta = yaml.safe_load(frontmatter)
                title = meta.get("title", os.path.basename(filepath))
                knowledge[title.lower()] = body.strip()
    return knowledge

# 2. Search OKF (deterministic, keyword-based)
def search_okf(query: str, okf_knowledge: dict) -> str | None:
    """Simple keyword match against OKF titles."""
    for title, content in okf_knowledge.items():
        if title in query.lower():
            return content
    return None

# 3. Search RAG (probabilistic, vector-based)
def search_rag(query: str) -> str:
    """Placeholder for your vector DB search (Pinecone, Weaviate, etc.)."""
    # results = vector_db.similarity_search(query, top_k=5)
    return "RAG context: [retrieved chunks would appear here]"

# 4. The Intelligent Router
def answer_query(query: str, okf_bundle_path: str) -> str:
    okf_knowledge = load_okf_bundle(okf_bundle_path)

    # Try OKF first (deterministic path)
    okf_result = search_okf(query, okf_knowledge)

    if okf_result:
        context = f"[SOURCE: Official Knowledge Base (OKF)]\n{okf_result}"
    else:
        # Fall back to RAG (probabilistic path)
        context = f"[SOURCE: Document Search (RAG)]\n{search_rag(query)}"

    # Send to LLM with the retrieved context
    response = client.chat.completions.create(
        model="gpt-4o",
        messages=[
            {"role": "system", "content": "Answer using ONLY the provided context."},
            {"role": "user", "content": f"Context:\n{context}\n\nQuestion: {query}"}
        ]
    )
    return response.choices[0].message.content

结论

将“结论”视为可度量的对象来处理效果最佳。在扩大范围之前，需记录一份理想样本、一个失败案例以及回滚说明。将此阶段视为输入与已验证输出之间的契约，为相关成果命名、明确成功标准，并杜绝默许的半完成状态。应将分块策略与检索策略分开，当质量指标发生变化时，修改其中一项不应强制要求重写另一项。

操作检查清单

将“操作检查清单”视为可度量的对象来处理效果最佳。在扩大范围之前，需记录一份理想样本、一个失败案例以及回滚说明。

优先选择小型且可测试的单元，而非庞大的脚本。当某一步骤失败时，故障应能指向单一责任点，而非复杂的流程链。

应将分块策略与检索策略分开。当质量指标发生变化时，修改其中一项不应强制重新编写另一项。

对于涉及资金支出或更改生产数据的操作，必须经过人工审批。编译时的配置并不等同于业务上的完整性。

编写简短的操作手册：说明如何轮换密钥、如何清空队列以及如何回滚上一次的数据导入操作。

将配置信息置于应用程序代码之外。环境文件、密钥存储和功能开关应集中存放于一个位置，以便操作人员无需查看整个系统结构即可进行审计。

在升级技术栈之前，先冻结现有版本，为关键流程保存完整的操作记录，并确认回滚步骤。共享环境需要设置速率限制、租户验证机制，以及明确的密钥轮换负责人。与其追求花哨的一次性演示，不如注重扎实的可靠性。

关于26b9ceed44f1的批处理说明：不要将提供者密钥放入代码仓库，为每个会话设置令牌上限，并将转录内容存储在评估测试用例的旁边，以便后续更换模型时仍能保持可比性。