本技能用于把兼容 OpenAI 的 LLM API 集成进应用、CLI、工具或服务。前提是先加载 myai 的 engineering-principles,本技能只覆盖如何与该 API 通信,属语言无关规则,示例为 Python 并附 TypeScript 参考,适用于任何有官方 OpenAI SDK 的语言。
用途与原则:使用官方 openai SDK,不要手写 HTTP 调用;使用 chat.completions 接口,通过 base_url 可对接 OpenAI、OpenRouter、Ollama 等兼容提供方。base_url、model、reasoning_effort 与 API key 都应可经环境变量、配置文件或应用设置覆盖,缺少 key 时快速失败并给出清晰错误。默认不发送 temperature 与 max_tokens,通常只传 model、messages、response_format,可选 reasoning_effort。
用法要点:一次性请求把全部内容放在单条 user 消息中,只有多轮对话才用 system 提示;提示词放在独立模板文件中(如 Jinja2),严格处理未定义变量。需要结构化结果时用 response_format 的 json_schema 并设 strict: true,必填字段用 required,禁止多余字段用 additionalProperties: false,范围用 minimum/maximum,并在响应侧再次校验。
容错与重试:部分提供方可能把 JSON 包在 markdown 代码围栏或散文里,可依次尝试裸 JSON、代码围栏内容、首个 { 到末个 } 的子串,提取时记 DEBUG 日志。使用手动重试循环,默认 3 次、指数退避,同时覆盖网络异常与校验失败;用尽后返回最后一次失败,不要吞掉。不要依赖 SDK 内置重试。
其他:SDK 是无类型的动态边界,应隔离在一个带类型的模块中,用可注入的调用接缝便于测试;空补全内容视为失败。图片输入用内容数组,文本在前、base64 data URL 在后。API key 绝不写进日志。资料还列出常见错误与相关技能,均为规则说明,未提供具体收费、平台或效果信息。