跳到主要内容

LTM 快速开始

下面的流程适合首次验证。需要一个 Turing API Key(见获取 API Key),以及可以使用的 Embedding 模型和 LLM family。Key 所属的 client 决定 Space 的归属:按用户隔离的 client(例如 Portal)创建的是当前用户的个人 Space,其他 client 创建的是 client 范围的 Space。

一条 Event 从提交到读取 Context 的 LTM 生命周期

先在 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。

下一步​

自助排查