LnkChat Capability API 快速入门指南

认证方式

LnkChat Capability API 采用 API Key + Bearer Token 双层认证机制。

API Key 是账户级凭证，在 LnkChat 管理后台「开发者设置 → API 密钥」页面创建。对于需要用户上下文的接口，需先通过 API Key 换取短期 Bearer Token（有效期 2 小时，过期前 5 分钟可续签）。

获取 Bearer Token

curl -X POST https://api.lanlnk.cn/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "lk_live_your_api_key_here",
    "api_secret": "lk_live_your_api_secret_here"
  }'

响应示例：

{
  "code": 0,
  "message": "success",
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "token_type": "Bearer",
    "expires_in": 7200,
    "refresh_token": "rt_9f8a7b6c5d4e3f2g1h0i..."
  }
}

安全提示：API Key 和 Secret 切勿硬编码到前端代码或公开仓库中。

基础信息

API 基础地址：https://api.lanlnk.cn/v1
协议：HTTPS（强制 TLS 1.2+）
数据格式：JSON（UTF-8 编码）
请求方式：RESTful（GET / POST）
限流策略：默认 60 次/分钟，可按需扩容

所有请求需携带公共 Header：Content-Type: application/json、Authorization: Bearer <access_token>、X-LnkChat-Client: <your_client_identifier>。

核心 API 端点

3.1 AI 客服对话接口

支持多轮上下文、意图识别和知识库增强回答。

POST /chat/customer-service：客服对话（同步）
POST /chat/stream：客服对话（SSE 流式）

核心参数：session_id（会话 ID）、message（用户消息）、knowledge_base（知识库标识）、temperature（生成温度，默认 0.7）、max_tokens（默认 1024）。

curl 示例（同步）：

curl -X POST https://api.lanlnk.cn/v1/chat/customer-service \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -d '{
    "session_id": "sess_a1b2c3d4",
    "message": "我的订单什么时候发货？",
    "knowledge_base": "kb_faq_shipping",
    "temperature": 0.5,
    "max_tokens": 512
  }'

响应包含 reply（回复内容）、intent（意图标签）、sources（知识来源）、tokens_used（Token 用量）。

SSE 流式响应以 Server-Sent Events 格式逐 Token 返回。

3.2 AI BI 问数接口

将自然语言转换为数据查询，返回结构化结果。

POST /bi/ask：自然语言问数
POST /bi/explain：查询 SQL 解释

核心参数：datasource_id（数据源 ID）、question（自然语言问题）、chart_type（图表类型）、limit（结果行数限制）。

响应包含自动生成的 SQL、列定义、数据行和自然语言摘要。

3.3 AI 知识库检索接口

对企业知识库执行语义检索。

POST /knowledge/search：语义检索
POST /knowledge/ingest：文档入库
GET /knowledge/documents：文档列表

核心参数：knowledge_base、query、top_k（返回数量，默认 5）、score_threshold（相似度阈值，默认 0.5）、filters（元数据过滤）。

响应包含匹配文档片段，附带来源、评分和元数据。

错误码说明

常见错误码：

40001（400）：请求参数缺失或格式错误
40101（401）：未认证或 Token 无效
40102（401）：Token 已过期
40301（403）：无接口访问权限
42901（429）：请求频率超限
50001（500）：服务内部错误
50301（503）：服务暂时不可用

重试建议：对于 429、500、503 错误，建议使用指数退避策略（初始间隔 1 秒，最大间隔 32 秒），最多重试 5 次。

SDK 语言支持

Python SDK

pip install lnkchat-sdk

from lnkchat import LnkChatClient

client = LnkChatClient(
    api_key="lk_live_your_api_key",
    api_secret="lk_live_your_api_secret"
)

# AI 客服对话
resp = client.chat.customer_service(
    message="我的订单什么时候发货？",
    knowledge_base="kb_faq_shipping"
)
print(resp.data.reply)

# AI BI 问数
result = client.bi.ask(
    datasource_id="ds_sales_2026",
    question="上月各区域销售额对比"
)

# 知识库检索
docs = client.knowledge.search(
    knowledge_base="kb_hr_handbook",
    query="年假天数规定",
    top_k=3
)

Java SDK

<!-- Maven -->
<dependency>
    <groupId>cn.lanlnk</groupId>
    <artifactId>lnkchat-sdk</artifactId>
    <version>1.2.0</version>
</dependency>

Node.js SDK

npm install @lanlnk/lnkchat-sdk

import { LnkChatClient } from '@lanlnk/lnkchat-sdk';

const client = new LnkChatClient({
  apiKey: 'lk_live_your_api_key',
  apiSecret: 'lk_live_your_api_secret'
});

const resp = await client.chat.customerService({
  message: '我的订单什么时候发货？',
  knowledgeBase: 'kb_faq_shipping'
});

Webhook 回调说明

对于异步场景（BI 复杂查询、知识库批量入库），LnkChat 支持 Webhook 回调。

配置方式：在管理后台「开发者设置 → Webhook」页面配置，或通过 API 动态注册。

回调事件类型：

chat.session.ended：客服会话结束
bi.query.completed：BI 问数查询完成
bi.query.failed：BI 问数查询失败
knowledge.ingest.completed：文档入库完成
knowledge.index.updated：索引重建完成

回调验签：每次回调在 Header 中携带 X-LnkChat-Signature（HMAC-SHA256）。回调失败后自动重试最多 3 次（30 秒、2 分钟、10 分钟间隔），连续失败 10 次自动暂停。

最佳实践与注意事项

Token 管理：缓存 access_token 并在过期前续签，多实例部署使用分布式锁管理 Token
限流与并发：批量场景建议申请扩容，知识库批量入库使用批量接口（单次最多 50 条）
数据安全：生产环境切勿将 API Key 写入前端代码，Webhook 回调地址必须使用 HTTPS
从自研迁移：参考开发者中心的 MCP Integration Guide，逐步将现有系统工具层接入 LnkChat

获取帮助

技术文档：lanlnk.cn/developers
技术交流：联系我们
邮箱：guweiguo@lanlnk.com