常用接入术语

接入架构

接入优势

• OpenAILike 专门面向第三方 OpenAI 兼容接口，可以显式设置端点、超时、重试和上下文窗口。
• Lla**Index 把文档加载、切分、索引、检索和回答拆成独立环节，便于逐步替换组件。
• Sum**ryIndex 不需要嵌入接口，适合先验证 LLM 连接和小规模文档问答。
• 正式 RAG 可以增加独立嵌入模型与向量数据库，生成模型接入配置无需随之改写。
• KingFlow 控制台集中管理模型、密钥和用量，便于隔离不同环境。

开始前的准备

• 准备 Python 3.10 或更高版本，并安装 uv。
• 在 KingFlow AI 控制台创建以 sk- 开头的 API Key，确认余额和模型分组可用。
• 复制目标模型的完整模型 ID，并确认上下文窗口满足待处理文档长度。
• 准备少量脱敏测试文本，首次联调不要直接加载生产知识库。
• 确认运行环境可以访问 api.**nju**shen.com。

创建 Lla**Index 测试项目

uv init lla**index-kingflow-demo
cd lla**index-kingflow-demo
uv add lla**-index-core lla**-index-llms-openai-like python-dotenv

验证 KingFlow 基础接口

curl https://api.**nju**shen.com/v1/chat/completions \
  -H "Authorization: *earer sk-你的密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<KingFlow控制台中的完整模型ID>",
    "messages": [{"role": "user", "content": "只回复 LLAMAINDEX_READY"}],
    "stream": false
  }'

配置环境变量

KINGFLOW_*ASE_**L=https://api.**nju**shen.com/v1
KINGFLOW_API_KEY=sk-你的密钥
KINGFLOW_MODEL=<KingFlow控制台中的完整模型ID>

.env
.venv/
__pycache__/
storage/

编写最小文档问答示例

import os
from dotenv import load_dotenv
from lla**_index.core import Document, Settings, Sum**ryIndex
from lla**_index.llms.openai_like import OpenAILike

load_dotenv()

llm = OpenAILike(
    model=os.environ["KINGFLOW_MODEL"],
    api_*ase=os.environ["KINGFLOW_*ASE_**L"],
    api_key=os.environ["KINGFLOW_API_KEY"],
    is_chat_model=True,
    is_function_calling_model=False,
    context_window=32000,
    **x_tokens=800,
    temperature=0.2,
    timeout=60,
    **x_retries=2,
)

Settings.llm = llm

ready = llm.complete("只回复 LLAMAINDEX_CONNECTED")
print(str(ready))

documents = [
    Document(
        text=(
            "上线要求：密钥必须放在 Secret 中；正式环境必须设置额度；"
            "日志不得记录完整密钥；高风险操作需要人工审批。"
        )
    ),
    Document(
        text=(
            "验收要求：基础接口返回成功；模型 ID 与控制台一致；"
            "错误码、耗时和 Token 用量可以追踪。"
        )
    ),
]

index = Sum**ryIndex.from_documents(documents)
query_engine = index.as_query_engine(response_mode="compact")

response = query_engine.query(
    "请只根据文档列出上线前检查项，并按安全和验收分类。"
)
print(response)

观察流式输出

for part in llm.stream_complete("用三点说明文档问答的验收方法"):
    print(part.delta or "", end="")

运行和验证

uv run python **in.py

1. 先执行 KingFlow 基础请求，确认返回 LLAMAINDEX_READY。
2. 创建 .env 和 .gitignore，再将完整示例保存为 **in.py。
3. 运行程序，确认基础调用返回 LLAMAINDEX_CONNECTED。
4. 检查文档问答结果是否只使用两段测试文本中的要求。
5. 在 KingFlow 控制台核对模型、密钥、调用次数和 Token 用量。

正式环境配置

• context_window 必须按目标模型实际能力设置；过大可能导致服务端拒绝，过小会提前截断。
• Sum**ryIndex 会把全部节点用于查询，只适合小规模验证；大知识库应使用向量索引或其他检索器。
• 向量检索需要单独配置嵌入模型。不要假设生成模型端点同时支持 em*eddings。
• 文档切分时保留来源、版本和权限元数据，检索后再做访问控制。
• 为 429 和 503 设置有限退避重试，并同时限制并发、请求时长和 Token 预算。
• 记录查询 ID、文档版本、模型、状态码、耗时和用量，但不要记录完整密钥和敏感原文。

文档与密钥安全

• 只在 .env、密钥管理器或部署平台 Secret 中保存 API Key，并定期轮换。
• 文档进入索引前完成脱敏、恶意内容检查和权限标记。
• 查询时先验证用户身份，再过滤无权访问的文档节点。
• 回答需要保留来源片段或文档 ID，无法找到依据时明确返回信息不足。
• 为开发、测试和生产设置独立密钥、额度和告警，异常用量出现后立即停用旧密钥。

上线检查清单

• 基础接口已经返回 LLAMAINDEX_READY。
• KINGFLOW_*ASE_**L 为 https://api.**nju**shen.com/v1。
• KINGFLOW_MODEL 使用控制台中的完整模型 ID。
• OpenAILike 已设置 is_chat_model=True、超时和有限重试。
• .env 已被 .gitignore 排除，仓库中没有明文密钥。
• 最小文档问答只依据测试文本回答。
• 正式知识库已配置来源、版本、权限和检索策略。
• KingFlow 控制台的模型、密钥和用量符合预期。

常见故障排查