模型设置

iztro-ziwei-v3 和 iztro-qimen-v3 共用 OpenAI Agents SDK 标准 ModelSettings 中受支持的部分。设置属于 Agent 请求，不属于某一种术数模型。SDK 定义了某个字段，不代表托管模型一定支持它。

完整示例

下面把深度推理和非思考采样分开，因为 DeepSeek 不允许在同一个请求中同时使用这两类控制。

Python

from agents import ModelSettings
from openai.types.shared import Reasoning
from iztro_agents import iztro_qimen_agent, iztro_ziwei_agent

deep_settings = ModelSettings(
    reasoning=Reasoning(effort="high"),
    max_tokens=384000,
    tool_choice="auto",
    parallel_tool_calls=True,
    metadata={
        "current_datetime": "2026-07-20T14:30:00+08:00",
    },
    extra_body={
        "language": "zh",
    },
)

fast_settings = ModelSettings(
    reasoning=Reasoning(effort="none"),
    temperature=0.4,  # 或 top_p=0.9；不能同时设置。
    extra_body={"language": "zh"},
)

ziwei = iztro_ziwei_agent(model_settings=deep_settings)
qimen = iztro_qimen_agent(model_settings=fast_settings)

TypeScript

import type {ModelSettings} from '@openai/agents';
import {iztroQimenAgent, iztroZiweiAgent} from 'openai-iztro-agents';

const deepSettings: ModelSettings = {
  reasoning: {effort: 'high'},
  maxTokens: 384000,
  toolChoice: 'auto',
  parallelToolCalls: true,
  providerData: {
    language: 'zh',
    metadata: {
      current_datetime: '2026-07-20T14:30:00+08:00',
    },
  },
};

const fastSettings: ModelSettings = {
  reasoning: {effort: 'none'},
  temperature: 0.4, // 或 topP: 0.9；不能同时设置。
  providerData: {language: 'zh'},
};

const ziwei = iztroZiweiAgent({modelSettings: deepSettings});
const qimen = iztroQimenAgent({modelSettings: fastSettings});

真实的奇门请求应在每一轮根据用户当地时间创建时间戳。固定写死的 current_datetime 只适合测试、重放和可复现示例。

完整支持矩阵

控制项	Python	TypeScript	原始 Chat API	Iztro 行为
推理强度	reasoning=Reasoning(effort=...)	reasoning: {effort: ...}	reasoning_effort	选择快速或深度推理路径
输出上限	max_tokens	maxTokens	max_tokens	限制生成的输出 token
温度	temperature	temperature	temperature	仅非思考模式，范围 0 到 2；不能和 top-p 同时设置
核采样	top_p	topP	top_p	仅非思考模式，范围 0 到 1；不能和温度同时设置
频率惩罚	frequency_penalty	frequencyPenalty	frequency_penalty	DeepSeek 不支持；托管 API 会拒绝
存在惩罚	presence_penalty	presencePenalty	presence_penalty	DeepSeek 不支持；托管 API 会拒绝
开发者工具模式	tool_choice	toolChoice	tool_choice	只控制开发者提供的工具
并行开发者工具	parallel_tool_calls	parallelToolCalls	parallel_tool_calls	允许一轮调用多个开发者工具
问事时刻	metadata.current_datetime	providerData.metadata.current_datetime	metadata.current_datetime	设置用户当地问事时间
回复语言	extra_body.language	providerData.language	language	强制只使用一种回复语言
托管 Iztro 工具	extra_body.enable_iztro_call	providerData.enable_iztro_call	enable_iztro_call	开关服务端命盘计算

推理、token、采样和开发者工具控制都是 SDK 标准字段，但只有上表明确标记支持的行为才是托管模型控制。language、current_datetime 和 enable_iztro_call 是通过 SDK 标准提供方扩展字段传递的 Iztro 请求扩展。

推理强度

Iztro 将标准 effort 值映射到两条执行路径：

推理强度	Iztro 执行路径	适合场景
省略 / none / minimal / low	更快的非思考模型	日常聊天、连续追问和相对直接的解读
medium / high / xhigh / 原始 HTTP max	使用 high 强度的深度推理模型	完整紫微报告、复杂盘面综合，以及需要多项证据交叉判断的奇门决策

需要深度结果时使用 high。当前 Python 和 TypeScript Agents SDK 类型支持到 xhigh；原始 HTTP 还接受 max，Iztro 有意将所有深度值统一映射为提供方的 high 强度。不要发送自定义 thinking 字段或 Iztro 自定义值 "deep"。

复杂盘的准确性

非思考模式优先速度，面对复杂盘时更容易遗漏或错配宫位、四化、时运层级及奇门证据。跨宫综合、多层运势，或需要结合盘面与应期证据的奇门决策，应使用 high。深度推理在这些场景通常更准确，但不保证绝对正确；结论仍应以托管工具返回的盘面事实为依据。

推理强度不控制回答长度；输出上限请单独使用 max_tokens 或 maxTokens。

输出上限

省略输出上限时，两个公开模型默认使用当前配置的 DeepSeek 最大值：384,000 个输出 token。完整紫微报告，以及可能先排盘再计算应期的奇门问题，建议直接省略该设置。

只有应用确实需要硬性成本或延迟边界时，才设置较低上限：

ModelSettings(max_tokens=12000)

const modelSettings = {maxTokens: 12000};

上限过低可能在盘面证据和时间结论全部写完前结束多步骤回答。达到上限时，API 返回 finish_reason: "length"。

采样设置

temperature 和 top_p / topP 只在非思考路径生效。只设置其中一个，或者都省略以使用模型默认值：

ModelSettings(
    reasoning=Reasoning(effort="none"),
    temperature=0.4,
)

深度推理会忽略这两个控制，因此 Iztro 会拒绝这种组合，不会接受一个实际无法生效的设置。DeepSeek 已废弃且不再支持 frequency_penalty / frequencyPenalty 和 presence_penalty / presencePenalty，Iztro 在所有模式下都会拒绝它们。

回复语言

支持 zh、en、ko、ja、vi。指定后，所有面向用户的标题、正文、列表、结论、提醒、工具进度说明和翻译后的术数术语都只使用该语言，不夹杂源语言，也不会在译名后括注原文。

代码、URL、模型名、API/工具/事件标识和 JSON 键保持原样。不传 language 时，模型自动跟随当前对话语言。

时间和应用指令

metadata.current_datetime 应使用带 UTC 偏移量的用户当地 ISO 8601 时间。奇门盘由问事时刻决定，因此这个字段尤其重要。

原始 Chat API 的 metadata 还支持 system_prompt_override，用于添加最多 8,000 字符的应用指令：

{
  "metadata": {
    "current_datetime": "2026-07-20T14:30:00+08:00",
    "system_prompt_override": "先给结论，再分别说明盘面证据和现实行动建议。"
  }
}

工具控制

tool_choice 和 parallel_tool_calls 只作用于应用提供的函数或 MCP 工具。紫微和奇门托管计算始终隐藏，并通过 Iztro 工具事件报告。只有回答必须完全依赖应用已经提供的上下文时，才使用 enable_iztro_call: false。

不属于托管模型契约的 SDK 字段

Agents SDK 同时服务多个提供方，并覆盖 Chat Completions 和 Responses API，所以它还定义了更多 ModelSettings 字段。以下字段当前不是 Iztro 托管模型控制项：

• 推理摘要以及 verbosity / text.verbosity；
• DeepSeek 已不再支持的 frequency_penalty 和 presence_penalty；
• store、提示缓存保留时间、截断策略、额外响应内容和 top log probabilities；
• 除本文记录的 Iztro 扩展外，其他任意提供方字段。

重试策略、额外请求头等 SDK 运行或传输选项仍由 SDK 自己处理。Iztro 会自动返回 usage，无需开发者额外打开。

原始 HTTP 示例

{
  "model": "iztro-qimen-v3",
  "reasoning_effort": "high",
  "max_tokens": 384000,
  "language": "zh",
  "messages": [
    {
      "role": "user",
      "content": "现在应该推进这项合作，还是继续谈判？请说明盘面证据和适合行动的时间。"
    }
  ],
  "metadata": {
    "current_datetime": "2026-07-20T14:30:00+08:00"
  }
}