LTM 快速开始
下面的流程适合首次验证。需要一个 Turing API Key(见获取 API Key),以及可以使用的 Embedding 模型和 LLM family。Key 所属的 client 决定 Space 的归属:按用户隔离的 client(例如 Portal)创建的是当前用户的个人 Space,其他 client 创建的是 client 范围的 Space。
先在 LTM 开发者平台 的工作区里完成一次同样的流程,再把请求复制到应用,最容易理解每个 API 返回值代表什么。
1. 设置环境变量
export TURING_BASE_URL="https://live-turing.cn.llm.tcljd.com/api/v1"
export TURING_API_KEY="<your-api-key>"
TURING_BASE_URL 必须包含 /api/v1。测试环境请替换为对应环境的 API 地址。示例使用中国区地址,亚太(新加坡)区和欧洲区的地址见可用区域。
2. 查看模型并创建 Space
curl "$TURING_BASE_URL/ltm/families" \
-H "Authorization: Bearer $TURING_API_KEY"
curl "$TURING_BASE_URL/ltm/spaces" \
-H "Authorization: Bearer $TURING_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "customer-support",
"description": "Support conversations",
"embedding_model": "<embedding-model>",
"model_profile": {"default": "<llm-family>"}
}'
保存响应中的 data.space_id。Embedding 模型在 Space 创建后不可修改。
3. 写入 Event
export SPACE_ID="<space-id>"
export IDEMPOTENCY_KEY="$(uuidgen)"
curl "$TURING_BASE_URL/ltm/spaces/$SPACE_ID/events" \
-H "Authorization: Bearer $TURING_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $IDEMPOTENCY_KEY" \
-d '{
"owner_type": "actor",
"actor_id": "user-123",
"session_id": "quickstart-session",
"messages": [
{"role": "user", "content": "我偏好用中文。"},
{"role": "assistant", "content": "记住了。"}
]
}'
成功返回 202 和 data.status = "accepted",data.event_id 是这条 Event 的 ID。
Idempotency-Key 在同一个 Space 内绑定第一次提交的内容:用同一个 key 重试同一请求,返回的是原来那条 Event,不会重复写入;同一个 key 配不同内容会返回 409。每条新 Event 都使用新的 key。
4. 确认派生完成
派生在后台进行,通常需要几十秒。不要固定等待一段时间,用 查询 LTM Event 派生状态 每隔几秒查一次,直到 data.status 不再是 in_progress:
export EVENT_ID="<event-id>"
# 每 5 秒查一次,最多 60 次(约 5 分钟)
for _ in $(seq 60); do
STATUS=$(curl -sf "$TURING_BASE_URL/ltm/spaces/$SPACE_ID/events/$EVENT_ID/derivation" \
-H "Authorization: Bearer $TURING_API_KEY" | jq -r '.data.status')
[ "$STATUS" = "in_progress" ] || break
sleep 5
done
echo "${STATUS:-request failed}"
请求失败时打印 request failed;5 分钟后仍未完成时打印 in_progress。
completed:已处理完。data.strategies里每个已启用的策略各有一条状态,no_candidates表示这段对话里没有这个策略需要长期保存的信息(例如寒暄)。dead_lettered:至少一个策略多次尝试都失败了,error_category给出原因类别,等原因消除后可以调用 重跑 LTM Event 派生。
其他状态的含义见 LTM 常见问题。
5. 读取上下文
curl "$TURING_BASE_URL/ltm/spaces/$SPACE_ID/context?actor_id=user-123&token_budget=2000" \
-H "Authorization: Bearer $TURING_API_KEY"
需要语义检索时使用 Search LTM memories;需要浏览全部记录时使用 List LTM memories。
下一步
- 不想自己编排 Recall 和 Capture:看 Managed Chat 接入。
- 正在开发本地 Agent:看 CLI + Skills 接入。
- 需要字段级契约:看 LTM API 参考。
- 想知道会召回什么、哪些参数可以调:看 LTM 使用指南。
- 遇到问题:看 LTM 常见问题。