化工热力学软件：HYSYS二次开发_（20）.使用Python进行HYSYS二次开发—

1. 化工工程师的 HYSYS 二次开发，为什么卡在“接 AI”这一步

HYSYS 二次开发做到一定深度，你会发现纯数值计算和流程模拟已经不够用了。比如你想让脚本自动读一批工况数据、生成优化建议、再把结论写回 HYSYS 的流股表，中间那段“理解数据、生成文本、做决策”的逻辑，用传统 if-else 写起来又臭又长。这时候把大模型能力接进 Python 脚本，是很自然的选择。

但真正动手时，卡点往往不在 HYSYS 的 COM 接口，而在“怎么让本地 Python 环境稳定调用外部 AI 服务”。化工工程师的电脑上通常装着 Aspen 全家桶、MATLAB、各种驱动，环境本来就重；再叠一层 API Key 管理、代理配置、SDK 版本冲突，调试时间直接翻倍。我见过不少同行，HYSYS 的pyodbc连接写得飞起，结果在 AI 接入这一步耗掉一整个下午。

这篇就聚焦这个环节：在 HYSYS 二次开发的 Python 工程里，用 TaoToken 统一 Key 把外部 AI 通道接进来，交付可复制的settings.json和config.toml骨架、CC Switch / Cline 的配置片段，再给一套连通性验证动作和报错排查清单。目标很明确——一次跑通，别在环境上反复折腾。

适合谁看：已经在用 Python 操作 HYSYS、想给脚本加 AI 能力的化工工程师；或者正在搭本地工程环境、需要统一管理多个 AI 通道的开发者。下面所有配置都基于本地工程目录，不涉及任何网络层特殊操作。

2. TaoToken 前置：统一 Key 与通道准备

TaoToken 在这里扮演的角色，是一个统一的 API 入口。你不需要在脚本里分别维护多个厂商的 Key 和 endpoint，而是用一套 Key、一个 base_url，通过模型名切换不同能力。对 HYSYS 二次开发场景来说，好处很直接：脚本里的配置项从“一堆散落的 Key”收敛成“一个 Key + 一个地址”，换模型只改一个字符串。

先做两件前置动作。

第一，拿到你的 API Key。登录后进入控制台，在 API Keys 页面创建一个新 Key。建议按项目命名，比如hysys-dev，方便后面排查是哪个脚本在调用。创建后立刻复制保存，页面刷新后就不再完整显示。

第二，确认你要用的模型名。TaoToken 的模型对话页面可以直接试跑，输入一段化工相关的 prompt，看返回是否正常。这一步别跳过——先在网页端确认通道可用，再去配本地环境，能把“Key 问题”和“本地配置问题”分开定位。

关键地址记一下：

官网入口：https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=
API 基地址：https://taotoken.net/api
控制台 / API Keys：https://taotoken.net/console/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=
模型对话试用：https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=
接入文档：https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=

注意：API 基地址统一用https://taotoken.net/api，不要在后面手动拼/v1之类的路径，具体路径由 SDK 或客户端按文档拼接。配错路径是后面 404 报错的高频原因。

3. 可复制配置：settings.json 与 config.toml 骨架

HYSYS 二次开发的 Python 工程，我习惯把 AI 配置和 HYSYS 连接配置分开存放。HYSYS 那边是pyodbc的连接串，AI 这边是 Key 和 base_url。下面给两份骨架，你可以直接复制到工程根目录。

3.1 settings.json 骨架

这份适合给 Cline、Continue 这类读取 JSON 配置的客户端用，也方便 Python 脚本自己json.load读取。

{ "ai": { "provider": "taotoken", "base_url": "https://taotoken.net/api", "api_key": "sk-你的TaoTokenKey", "default_model": "claude-sonnet-4-20250514", "timeout_seconds": 60, "max_retries": 2 }, "hysys": { "driver": "HYSYS Driver", "server": "localhost", "database": "HYSYS", "uid": "your_username", "pwd": "your_password" }, "project": { "name": "hysys-ai-dev", "log_level": "INFO" } }

几个参数说明：timeout_seconds给 60 秒，是因为化工数据批量处理时 prompt 可能较长；max_retries设 2，避免偶发网络抖动直接让脚本崩掉。default_model先填一个你在模型对话页面验证过的名字，后面换模型只改这一行。

3.2 config.toml 骨架

如果你用的是支持 TOML 的工具链，或者想把配置写得更“工程化”，用这份。

[ai] provider = "taotoken" base_url = "https://taotoken.net/api" api_key = "sk-你的TaoTokenKey" default_model = "claude-sonnet-4-20250514" timeout_seconds = 60 max_retries = 2 [ai.headers] Content-Type = "application/json" [hysys] driver = "HYSYS Driver" server = "localhost" database = "HYSYS" uid = "your_username" pwd = "your_password" [project] name = "hysys-ai-dev" log_level = "INFO"

Python 侧读取 TOML 用标准库tomllib（3.11+）或tomli：

import tomllib with open("config.toml", "rb") as f: cfg = tomllib.load(f) base_url = cfg["ai"]["base_url"] api_key = cfg["ai"]["api_key"] model = cfg["ai"]["default_model"] print(f"AI endpoint: {base_url}, model: {model}")

注意：api_key不要提交到 Git。把settings.json和config.toml加进.gitignore，仓库里只放settings.example.json和config.example.toml。

3.3 CC Switch / Cline 配置片段

如果你在 VS Code 里用 Cline 做辅助编码，配置入口在 Cline 的设置面板，选 “OpenAI Compatible” 或自定义 provider，然后填：

{ "apiProvider": "openai", "openAiBaseUrl": "https://taotoken.net/api", "openAiApiKey": "sk-你的TaoTokenKey", "openAiModelId": "claude-sonnet-4-20250514" }

CC Switch 这类多通道切换工具，核心也是三件事：base_url 填https://taotoken.net/api，Key 填 TaoToken 的 Key，模型名填你在模型对话页面确认过的名字。切换通道时只改这三项，不要动其他默认参数。

4. 验证请求：从 Python 侧确认通道打通

配置写完，别急着往 HYSYS 主脚本里塞。先单独跑一个最小验证脚本，确认通道可用。

4.1 最小连通性脚本

import json import urllib.request with open("settings.json", "r", encoding="utf-8") as f: cfg = json.load(f) ai = cfg["ai"] url = f"{ai['base_url']}/v1/chat/completions" payload = { "model": ai["default_model"], "messages": [ {"role": "user", "content": "用一句话说明化工流程模拟中自由度分析的作用。"} ], "max_tokens": 200 } req = urllib.request.Request( url, data=json.dumps(payload).encode("utf-8"), headers={ "Content-Type": "application/json", "Authorization": f"Bearer {ai['api_key']}" }, method="POST" ) try: with urllib.request.urlopen(req, timeout=ai["timeout_seconds"]) as resp: result = json.loads(resp.read().decode("utf-8")) print("状态码:", resp.status) print("模型返回:", result["choices"][0]["message"]["content"]) except urllib.error.HTTPError as e: print("HTTP 错误:", e.code) print("错误详情:", e.read().decode("utf-8")) except Exception as e: print("请求异常:", repr(e))

跑通的话，你会看到状态码 200 和一段关于自由度分析的文本。这一步成功，说明 Key、base_url、模型名三者都对上了。

4.2 把 AI 调用嵌进 HYSYS 数据流

验证通过后，再把它接到 HYSYS 数据读取之后。下面是一个简化示例：从 HYSYS 读流股数据，拼成 prompt，让模型给优化建议。

import json import urllib.request import pyodbc import pandas as pd with open("settings.json", "r", encoding="utf-8") as f: cfg = json.load(f) conn_str = ( f"DRIVER={{{cfg['hysys']['driver']}}};" f"SERVER={cfg['hysys']['server']};" f"DATABASE={cfg['hysys']['database']};" f"UID={cfg['hysys']['uid']};" f"PWD={cfg['hysys']['pwd']}" ) conn = pyodbc.connect(conn_str) cursor = conn.cursor() cursor.execute("SELECT * FROM StreamData WHERE StreamID = '1'") rows = cursor.fetchall() df = pd.DataFrame(rows, columns=[d[0] for d in cursor.description]) cursor.close() conn.close() prompt = ( "以下是 HYSYS 中一条流股的数据，请用化工热力学视角给出三条优化建议，" "每条不超过 50 字：\n" + df.to_string(index=False) ) ai = cfg["ai"] payload = { "model": ai["default_model"], "messages": [{"role": "user", "content": prompt}], "max_tokens": 500 } req = urllib.request.Request( f"{ai['base_url']}/v1/chat/completions", data=json.dumps(payload).encode("utf-8"), headers={ "Content-Type": "application/json", "Authorization": f"Bearer {ai['api_key']}" }, method="POST" ) with urllib.request.urlopen(req, timeout=ai["timeout_seconds"]) as resp: result = json.loads(resp.read().decode("utf-8")) print(result["choices"][0]["message"]["content"])

这段代码把 HYSYS 数据读取和 AI 调用串起来了。实测下来，只要第 4.1 步能通，这一步基本不会卡在通道上，问题通常出在数据格式或 prompt 长度。

5. 本篇常见错排查清单

配置环节的报错，八成集中在下面几类。按顺序排查，能省不少时间。

401 Unauthorized：Key 错了或没带上。检查Authorization头是不是Bearer sk-xxx格式，中间有没有多余空格。如果 Key 是从网页复制的，注意别把首尾空白带进去。

404 Not Found：base_url 拼错。确认是https://taotoken.net/api，不要写成https://taotoken.net/api/v1再让 SDK 拼一次。路径重复是 404 的常见原因。

400 Bad Request：模型名不对，或 payload 结构有问题。先去模型对话页面确认模型名拼写，再检查messages是不是标准数组格式。

超时 / Connection reset：timeout_seconds太短，或本地网络环境有干扰。把超时调到 60 秒以上再试；如果批量处理，考虑加max_retries做重试。

JSON 解析失败：settings.json里有中文引号、尾逗号或注释。JSON 不支持注释，用python -m json.tool settings.json校验一下。

HYSYS 连接正常但 AI 调用失败：说明问题在 AI 配置层，不在 HYSYS 层。把第 4.1 步的最小脚本单独跑一遍，隔离变量。

注意：排查时一次只改一个变量。同时改 Key、base_url 和模型名，出错了你也不知道是哪个的问题。

6. 配置跑通之后，往哪走

配置这件事，跑通一次之后就该把它固化下来。我的做法是把settings.json里的 AI 配置抽成一个ai_client.py模块，HYSYS 脚本只 import 这个模块，不直接碰 Key 和 URL。这样换模型、换通道只改一处，脚本本身不动。

如果你后面要做长期的编码辅助或 Agent 类任务，比如让脚本自动读 HYSYS 报表、生成优化方案、再写回结果，可以考虑用 Coding Plan 这类按周期计费的方式，比按次调用更适合高频场景。入口在 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。

日常调试和模型验证，直接用模型对话页面最快：https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。接入细节和参数说明看文档：https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。Key 管理在控制台：https://taotoken.net/console/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。

最后留一个我踩过的坑：HYSYS 的pyodbc连接和 AI 的 HTTP 请求不要在同一个 try 块里混着写。HYSYS 连接失败和 AI 调用失败，排查路径完全不同，混在一起日志会很难读。分开写，分开打日志，出问题时一眼就能定位是哪一层。