本教程将详细讲解如何在 Python 环境中通过天工 AI 的 SDK 进行语义分析。您需要先完成几个关键前置步骤：安装最新版 SDK、正确配置 API 密钥、初始化客户端，最后再调用 text_analysis 接口。如果遗漏其中任何一步，请求就会失败——通常表现为认证错误或参数不完整。下面将一步步说明每个环节。

安装天工AI Python SDK

打开终端，直接执行 pip install tiangong-sdk 即可完成安装。有一点需要特别留意：Python 版本必须为 3.8 及以上，低版本可能因依赖冲突导致导入失败，届时排查起来会非常麻烦。

获取并配置API密钥

登录天工AI开放平台（https://platform.tiangong.cn），进入「控制台 → API密钥管理」，创建新密钥后会获得 APP_KEY 和 APP_SECRET。密钥生成后无法再次查看明文，请务必立即保存到安全位置；万一丢失，只能删除重建，旧密钥会马上失效。

在项目根目录下新建 .env 文件，写入以下内容：

TIANGONG_APP_KEY=your_app_key_here
TIANGONG_APP_SECRET=your_app_secret_here

初始化客户端并调用语义分析接口

初始化客户端有三种方式，您可以根据实际需求选择。

方法一：使用环境变量自动加载

import os
from tiangong import TiangongClient

client = TiangongClient()  # 自动读取 .env 中的 APP_KEY 和 APP_SECRET

方法二：显式传入凭证（适合临时调试）

client = TiangongClient(
    app_key="your_app_key",
    app_secret="your_app_secret"
)

方法三：从环境变量手动提取（便于进行密钥校验）

app_key = os.getenv("TIANGONG_APP_KEY")
app_secret = os.getenv("TIANGONG_APP_SECRET")
if not app_key or not app_secret:
    raise ValueError("缺少 TIANGONG_APP_KEY 或 TIANGONG_APP_SECRET 环境变量")
client = TiangongClient(app_key, app_secret)

执行语义分析任务

首先准备一段待分析的文本：

text = "这个产品设计简洁，但操作逻辑不够直观，用户反馈学习成本偏高。"

接着调用 text_analysis 方法，指定分析类型为 sentiment（情感）和 intent（意图）：

result = client.text_analysis(
    text=text,
    analysis_types=["sentiment", "intent"]
)

最后解析返回结果中的核心字段：

print("情感倾向：", result["sentiment"]["label"])  # 输出：negative / neutral / positive
print("主意图：", result["intent"]["label"])         # 输出：complaint / suggestion / praise

这里有一个容易踩的坑：analysis_types 参数必须为列表形式，即使只分析一种类型也要写成 ["sentiment"]，如果直接传字符串会报错，请务必注意。