llm-integration

LLM 集成

将 LLM 集成到生产应用程序的模式：工具使用、流式传输、本地推理和微调。每个类别都有单独的规则文件，存放在 rules/ 中，按需加载。

快速参考

类别	规则	影响	使用时机
函数调用	3	严重	工具定义、并行执行、输入验证
流式传输	3	高	SSE 端点、结构化流式传输、背压处理
本地推理	3	高	Ollama 配置、模型选择、GPU 优化
微调	3	高	LoRA/QLoRA 训练、数据集准备、评估
上下文优化	2	高	窗口管理、压缩、缓存、预算扩展
评估	2	高	LLM-as-judge、RAGAS 指标、质量门槛、基准测试
提示词工程	4	高	CoT、少样本、版本管理、DSPy 优化、ReAct、成本优化

共计：7 个类别中的 20 条规则

快速开始

# Function calling: strict mode tool definition
tools = [{
    "type": "function",
    "function": {
        "name": "search_documents",
        "description": "Search knowledge base",
        "strict": True,
        "parameters": {
            "type": "object",
            "properties": {
                "query": {"type": "string", "description": "Search query"},
                "limit": {"type": "integer", "description": "Max results"}
            },
            "required": ["query", "limit"],
            "additionalProperties": False
        }
    }
}]

# Streaming: SSE endpoint with FastAPI
@app.get("/chat/stream")
async def stream_chat(prompt: str):
    async def generate():
        async for token in async_stream(prompt):
            yield {"event": "token", "data": token}
        yield {"event": "done", "data": ""}
    return EventSourceResponse(generate())

# Local inference: Ollama with LangChain
llm = ChatOllama(
    model="deepseek-r1:70b",
    base_url="http://localhost:11434",
    temperature=0.0,
    num_ctx=32768,
)

# Fine-tuning: QLoRA with Unsloth
model, tokenizer = FastLanguageModel.from_pretrained(
    model_name="unsloth/Meta-Llama-3.1-8B",
    max_seq_length=2048, load_in_4bit=True,
)
model = FastLanguageModel.get_peft_model(model, r=16, lora_alpha=32)

函数调用

让 LLM 使用外部工具并返回结构化数据。为确保可靠性，使用严格模式架构（2026 年最佳实践）。在 Claude 上，保持各轮对话中的 tools 数组稳定，以维持提示词缓存；在会话中途添加工具时，使用内联 tool_addition（beta inline-tools-2026-09-15，仅限 Claude API，Sonnet 5.5 支持，Sonnet 5 不支持），而不是替换工具子集（https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages#mid-conversation-tool-changes）。对于大型工具集，使用一个非延迟工具搜索工具，并在其余工具上设置 defer_loading: true；绝不要单独使用 defer_loading（请求中的工具不能全部设为延迟加载）。在 Sonnet 5.5、Opus 5.5、Fable 5.1 和 Mythos 5.1 上，强制指定 tool_choice（any 或命名工具）会返回 400；请对 strict: true 工具使用 auto。使用 Pydantic/Zod 验证所有输入，并将错误作为工具结果返回。

• calling-tool-definition.md -- 严格模式架构、OpenAI/Anthropic 格式、LangChain 绑定
• calling-parallel.md -- 并行工具执行、asyncio.gather、严格模式约束
• calling-validation.md -- 输入验证、错误处理、工具执行循环

流式传输

实时传送 LLM 响应，改善用户体验。Web 应用使用 SSE，双向通信使用 WebSocket。通过有界队列处理背压。

• streaming-sse.md -- FastAPI SSE 端点、前端消费者、异步迭代器
• streaming-structured.md -- 使用工具调用进行流式传输、部分 JSON 解析、分块累积
• streaming-backpressure.md -- 背压处理、有界缓冲区、取消操作

本地推理

使用 Ollama 在本地运行 LLM，以节省成本（相比云端节省 93%）、保护隐私并支持离线开发。预热模型，并使用提供方工厂在云端和本地之间切换。

• local-ollama-setup.md -- 安装、拉取模型、环境配置
• local-model-selection.md -- 按任务进行模型比较、硬件配置、量化
• local-gpu-optimization.md -- Apple Silicon 调优、保持运行、CI 集成

微调

使用参数高效技术定制 LLM。只有在充分尝试提示词工程和 RAG 后，才进行微调。需要 1000 个以上的高质量示例。

• tuning-lora.md -- LoRA/QLoRA 配置、Unsloth 训练、适配器合并
• tuning-dataset-prep.md -- 合成数据生成、质量验证、去重
• tuning-evaluation.md -- DPO 对齐、评估指标、反模式

上下文优化

管理上下文窗口、压缩和注意力感知定位。针对每项任务的 token 用量进行优化。

• context-window-management.md -- 五层架构、锚定式摘要、压缩触发条件
• context-caching.md -- 即时加载、预算扩展、探测评估、CC 2.1.32+

评估

通过多维度评分、质量门槛和基准测试评估 LLM 输出。

• evaluation-metrics.md -- LLM-as-judge、RAGAS 指标、幻觉检测
• evaluation-benchmarks.md -- 质量门槛、批量评估、成对比较

提示词工程

为生产级 LLM 应用设计、版本管理和优化提示词。

• prompt-design.md -- 思维链、少样本学习、模式选择指南
• prompt-testing.md -- Langfuse 版本管理、DSPy 优化、A/B 测试、自洽性
• prompt-react-pattern.md -- 面向工具使用型 Agent 的 ReAct 循环、思考-行动-观察格式
• prompt-optimization.md -- 减少 Token、成本优化、模型分层、提示词规范格式

上游内容覆盖范围（不要重复说明）

这些主题由各供应商自己的文档介绍。本技能会指向这些文档，而非讲解相关内容；以上规则仅保留我们的底线、上限和经验教训。有关所有这些内容的差异说明，请参阅 references/ork-delta.md。

主题	一手来源
严格模式工具架构、结构化输出	https://platform.openai.com/docs/guides/function-calling
Anthropic input_schema / tool_use	https://docs.claude.com/en/docs/agents-and-tools/tool-use/overview
SSE 客户端机制、重连、取消	https://developer.mozilla.org/en-US/docs/Web/API/EventSource
LoRA / QLoRA 配置、目标模块、适配器合并	https://huggingface.co/docs/peft/developer_guides/lora
Unsloth 训练循环、4 位加载	https://docs.unsloth.ai/get-started/fine-tuning-llms-guide
DPO、偏好对、beta 调优、RLHF 对比	https://huggingface.co/docs/trl/dpo_trainer
SFT 数据集格式（Alpaca、ChatML）	https://huggingface.co/docs/trl/sft_trainer
用于数据集去重的嵌入相似度	https://sbert.net/
微调、提示词与 RAG 的决策框架	https://platform.openai.com/docs/guides/optimizing-llm-accuracy
供应商 Token 定价（切勿在此处硬编码）	https://platform.openai.com/docs/pricing

支持文件

• references/ork-delta.md -- 我们的差异说明：经验教训、内部上限、已弃用文件的来源
• references/model-selection.md -- 按任务和硬件比较本地模型
• scripts/create-lora-config.md -- 自动检测模型类型的 LoRA 配置框架

关键决策

决策	建议
工具架构模式	strict: true（2026 年最佳实践）
工具数量	预先加载约 5-15 个；其余工具通过一个不延迟加载的工具搜索工具按需加载
流式传输协议	Web 使用 SSE，双向通信使用 WebSocket
缓冲区大小	50-200 个 Token
本地模型（推理）	deepseek-r1:70b
本地模型（编码）	qwen2.5-coder:32b
微调方法	LoRA/QLoRA（先尝试提示词）
LoRA 秩	通常为 16-64
训练轮数	1-3（更多轮数会增加过拟合风险）
上下文压缩	锚定式迭代（60-80%）
压缩触发条件	利用率达到 70%，目标为 50%
评审模型	claude-haiku-5-5（成本档位）、gpt-5.5 或 gemini-3.8-flash（Google 的 GA 通用模型，也是满足不同模型规则的第三家供应商；价格记录在 models.vocab.json 中，而非此处）
质量阈值	生产环境为 0.7，草稿为 0.6
少样本示例	3-5 个多样且有代表性的示例
提示词版本管理	使用带标签的 Langfuse
自动优化	DSPy MIPROv2

相关技能

• ork:rag-retrieval -- 嵌入模式，以及何时 RAG 优于微调
• agent-loops -- 结合推理的多步骤工具使用
• llm-evaluation -- 评估微调模型和本地模型
• langfuse-observability -- 跟踪训练实验

能力详情

函数调用

关键词： tool、function、define tool、tool schema、function schema、strict mode、parallel tools 解决的问题：

• 使用清晰的描述和严格的架构定义工具
• 使用 asyncio.gather 并行执行工具调用
• 在工具执行循环中验证输入并处理错误

流式传输

关键词： streaming、SSE、Server-Sent Events、实时、反压、token 流 解决的问题：

• 通过 SSE 端点流式传输大模型 token
• 在流中处理工具调用
• 使用有界队列管理反压

本地推理

关键词： Ollama、本地、可自托管、模型选择、GPU、Apple Silicon 解决的问题：

• 配置 Ollama 以进行本地大模型推理
• 根据任务和硬件选择模型
• 优化 GPU 使用和 CI 集成

微调

关键词： LoRA、QLoRA、微调、DPO、合成数据、PEFT、对齐 解决的问题：

• 配置 LoRA/QLoRA，以进行参数高效训练
• 生成并验证合成训练数据
• 使用 DPO 对齐模型并评估结果