跳转到主要内容

Documentation Index

Fetch the complete documentation index at: https://docs.shannon.run/llms.txt

Use this file to discover all available pages before exploring further.

​
概述

Shannon 提供 OpenAI 兼容 API 层，使您可以通过现有的 OpenAI SDK、工具和集成来与 Shannon 的智能体编排平台交互。兼容层将 OpenAI 聊天补全请求转换为 Shannon 任务，并以 OpenAI 格式流式返回结果。 这意味着您可以将 OpenAI Python 或 Node.js SDK 指向 Shannon，即可使用多智能体研究、工具调用和深度分析功能——一切通过熟悉的接口完成。
OpenAI 兼容 API 旨在与现有工具兼容。如需完整的 Shannon 功能（技能、会话工作区、研究策略、任务控制），请使用原生 /api/v1/tasks 端点。

​
端点

方法路径描述
POST/v1/chat/completions创建聊天补全（支持流式和非流式）
GET/v1/models列出可用模型
GET/v1/models/{model}获取模型详情
基础 URL：http://localhost:8080（开发环境）

​
认证

OpenAI 兼容端点使用与其他 Shannon API 相同的认证方式。 
# Bearer 令牌（OpenAI SDK 默认方式）
Authorization: Bearer sk_your_api_key

# 或 X-API-Key 请求头
X-API-Key: sk_your_api_key
开发环境默认：设置 GATEWAY_SKIP_AUTH=1 时认证已禁用。生产环境请启用认证。

​
可用模型

Shannon 将模型名称映射到不同的工作流模式和策略。选择模型来控制请求的处理方式。
模型工作流模式描述默认最大 Token 数可用性
shannon-chatSimple通用聊天补全（默认）4096全部
shannon-standard-researchResearch中等深度的平衡研究4096全部
shannon-deep-researchResearch迭代精炼的深度研究8192全部
shannon-quick-researchResearch简单查询的快速研究4096全部
shannon-complexSupervisor复杂任务的多智能体编排8192全部
shannon-ads-researchAds Research多平台广告竞争分析8192仅限 Shannon Cloud
如果未指定模型，默认使用 shannon-chat。
仅限 Shannon Cloud：shannon-ads-research 模型是企业功能，仅适用于配置了广告研究供应商适配器的 Shannon Cloud 部署。
模型可通过 config/openai_models.yaml 自定义。有关添加自定义模型的详细信息，请参阅 Shannon 配置文档。

​
聊天补全

​
POST /v1/chat/completions

​
请求体

参数类型必需描述
modelstring否模型名称（默认 shannon-chat）
messagesarray是消息对象数组
streamboolean否启用流式传输（默认 false）
max_tokensinteger否响应最大 token 数（上限 16384）
temperaturenumber否采样温度 0-2（默认 0.7）
top_pnumber否核采样参数
ninteger否补全数量（仅支持 1）
stoparray否停止序列
presence_penaltynumber否存在惩罚 -2.0 到 2.0
frequency_penaltynumber否频率惩罚 -2.0 到 2.0
userstring否终端用户标识符，用于跟踪和会话推导
stream_optionsobject否流式选项（见下方）
消息对象：
字段类型必需描述
rolestring是system、user 或 assistant
contentstring是消息内容（仅文本）
namestring否参与者的可选名称
流式选项：
字段类型描述
include_usageboolean在最终流式块中包含 token 使用情况

​
消息处理方式

Shannon 将 OpenAI 消息数组转换为 Shannon 任务：
  • 最后一条用户消息成为任务查询
  • 第一条系统消息成为系统提示
  • 其他所有消息（不含系统消息和最后一条用户消息）成为对话历史
  • 模型名称决定工作流模式和研究策略

​
非流式响应

{
  "id": "chatcmpl-20250120100000a1b2c3d4",
  "object": "chat.completion",
  "created": 1737367200,
  "model": "shannon-chat",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Shannon 的响应文本..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 25,
    "completion_tokens": 150,
    "total_tokens": 175
  }
}
非流式请求有 35 分钟超时，以支持深度研究和长时间运行的工作流。对于很长的任务，建议使用流式模式。

​
流式响应

当 stream: true 时，响应以 Server-Sent Events 形式传输： 首个块（包含角色）： 
data: {"id":"chatcmpl-...","object":"chat.completion.chunk","created":1737367200,"model":"shannon-chat","choices":[{"index":0,"delta":{"role":"assistant","content":"响应"},"finish_reason":null}]}
内容块： 
data: {"id":"chatcmpl-...","object":"chat.completion.chunk","created":1737367200,"model":"shannon-chat","choices":[{"index":0,"delta":{"content":"文本内容"},"finish_reason":null}]}
最终块（包含结束原因）： 
data: {"id":"chatcmpl-...","object":"chat.completion.chunk","created":1737367200,"model":"shannon-chat","choices":[{"index":0,"delta":{},"finish_reason":"stop"}],"usage":{"prompt_tokens":25,"completion_tokens":150,"total_tokens":175}}
流终止符： 
data: [DONE]
最终块中的使用数据仅在 stream_options.include_usage 设置为 true 时包含。

​
Shannon 扩展

​
shannon_events 字段

在流式传输期间，Shannon 通过 shannon_events 字段扩展标准 OpenAI 块格式。该字段携带智能体生命周期事件，提供 Shannon 智能体幕后工作的可见性。 
{
  "id": "chatcmpl-...",
  "object": "chat.completion.chunk",
  "created": 1737367200,
  "model": "shannon-deep-research",
  "choices": [
    {
      "index": 0,
      "delta": {}
    }
  ],
  "shannon_events": [
    {
      "type": "AGENT_STARTED",
      "agent_id": "researcher_1",
      "message": "正在开始研究查询...",
      "timestamp": 1737367201,
      "payload": {}
    }
  ]
}
ShannonEvent 字段：
字段类型描述
typestring事件类型（见下表）
agent_idstring智能体标识符
messagestring人类可读的描述
timestampintegerUnix 时间戳
payloadobject附加的事件特定数据
转发的事件类型：
类别事件
工作流WORKFLOW_STARTED、WORKFLOW_PAUSING、WORKFLOW_PAUSED、WORKFLOW_RESUMED、WORKFLOW_CANCELLING、WORKFLOW_CANCELLED
智能体AGENT_STARTED、AGENT_COMPLETED、AGENT_THINKING
工具TOOL_INVOKED、TOOL_OBSERVATION
进度PROGRESS、DATA_PROCESSING、WAITING、ERROR_RECOVERY
团队TEAM_RECRUITED、TEAM_RETIRED、TEAM_STATUS、ROLE_ASSIGNED、DELEGATION、DEPENDENCY_SATISFIED
预算和审批BUDGET_THRESHOLD、APPROVAL_REQUESTED、APPROVAL_DECISION
标准 OpenAI 客户端会忽略未知字段，因此 shannon_events 字段可以安全地用于任何 OpenAI 兼容工具。当您需要更丰富的进度信息时，可以解析该字段。

​
X-Session-ID 请求头

Shannon 通过 X-Session-ID 请求头支持多轮对话。提供该请求头后，Shannon 会在请求之间维护对话上下文。 
curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Authorization: Bearer sk_your_key" \
  -H "X-Session-ID: my-conversation-1" \
  -H "Content-Type: application/json" \
  -d '{"model": "shannon-chat", "messages": [{"role": "user", "content": "你好"}]}'
如果未提供 X-Session-ID，Shannon 会根据对话内容（系统消息 + 第一条用户消息的哈希值）或 user 字段推导会话 ID。 当创建新会话或检测到冲突时，响应中会包含 X-Session-ID 和 X-Shannon-Session-ID 头。

​
速率限制

速率限制按 API 密钥、按模型执行。默认限制为：
  • 每个模型 每分钟 60 个请求
  • 每个模型 每分钟 200,000 个 token
每个响应中包含的速率限制头：
头部描述
X-RateLimit-Limit-Requests每分钟最大请求数
X-RateLimit-Remaining-Requests当前窗口剩余请求数
X-RateLimit-Limit-Tokens每分钟最大 token 数
X-RateLimit-Remaining-Tokens当前窗口剩余 token 数
X-RateLimit-Reset-Requests请求限制重置时间
Retry-After重试前等待的秒数（429 时）

​
错误处理

错误遵循 OpenAI 错误响应格式： 
{
  "error": {
    "message": "Model 'invalid-model' not found. Use GET /v1/models to list available models.",
    "type": "invalid_request_error",
    "code": "model_not_found"
  }
}
错误类型：
HTTP 状态码类型代码描述
400invalid_request_errorinvalid_request请求格式错误或缺少必需字段
401authentication_errorinvalid_api_keyAPI 密钥无效或缺失
403permission_errorinvalid_request权限不足
404invalid_request_errormodel_not_found模型不存在
429rate_limit_errorrate_limit_exceeded超出速率限制
500server_errorinternal_error内部服务器错误

​
列出模型

​
GET /v1/models

返回所有可用的 Shannon 模型。 
curl http://localhost:8080/v1/models \
  -H "Authorization: Bearer sk_your_key"
响应： 
{
  "object": "list",
  "data": [
    {
      "id": "shannon-chat",
      "object": "model",
      "created": 1737367200,
      "owned_by": "shannon"
    },
    {
      "id": "shannon-deep-research",
      "object": "model",
      "created": 1737367200,
      "owned_by": "shannon"
    }
  ]
}

​
GET /v1/models/

返回特定模型的详情。模型描述包含在 X-Model-Description 响应头中。 
curl http://localhost:8080/v1/models/shannon-deep-research \
  -H "Authorization: Bearer sk_your_key"

​
使用 OpenAI SDK

​
Python

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8080/v1",
    api_key="sk_your_api_key",  # 如果认证已禁用，使用 "not-needed"
)

# 非流式
response = client.chat.completions.create(
    model="shannon-chat",
    messages=[
        {"role": "system", "content": "你是一个有帮助的助手。"},
        {"role": "user", "content": "什么是 Shannon？"}
    ],
)
print(response.choices[0].message.content)

# 广告研究（仅限 Shannon Cloud）
response = client.chat.completions.create(
    model="shannon-ads-research",
    messages=[
        {"role": "user", "content": "分析有机护肤品的竞争对手广告"}
    ],
)
print(response.choices[0].message.content)

# 流式
stream = client.chat.completions.create(
    model="shannon-deep-research",
    messages=[
        {"role": "user", "content": "分析 AI 对医疗保健的影响"}
    ],
    stream=True,
    stream_options={"include_usage": True},
)

for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

    # 访问 Shannon 特有的事件（如果可用）
    if hasattr(chunk, "shannon_events") and chunk.shannon_events:
        for event in chunk.shannon_events:
            print(f"\n[{event['type']}] {event.get('message', '')}")

​
Node.js / TypeScript

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "http://localhost:8080/v1",
  apiKey: "sk_your_api_key",
});

// 非流式
const response = await client.chat.completions.create({
  model: "shannon-chat",
  messages: [
    { role: "user", content: "什么是 Shannon？" }
  ],
});
console.log(response.choices[0].message.content);

// 流式
const stream = await client.chat.completions.create({
  model: "shannon-deep-research",
  messages: [
    { role: "user", content: "分析 AI 对医疗保健的影响" }
  ],
  stream: true,
});

for await (const chunk of stream) {
  const content = chunk.choices[0]?.delta?.content;
  if (content) {
    process.stdout.write(content);
  }
}

​
curl

# 非流式
curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk_your_api_key" \
  -d '{
    "model": "shannon-chat",
    "messages": [
      {"role": "user", "content": "什么是 Shannon？"}
    ]
  }'

# 流式
curl -N -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk_your_api_key" \
  -d '{
    "model": "shannon-deep-research",
    "messages": [
      {"role": "user", "content": "分析 AI 对医疗保健的影响"}
    ],
    "stream": true,
    "stream_options": {"include_usage": true}
  }'

# 使用会话 ID 进行多轮对话
curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk_your_api_key" \
  -H "X-Session-ID: my-session-1" \
  -d '{
    "model": "shannon-chat",
    "messages": [
      {"role": "system", "content": "你是一个数据分析师。"},
      {"role": "user", "content": "总结第四季度收入趋势"}
    ]
  }'

​
带 Shannon 事件的流式传输

要构建显示智能体进度的丰富 UI，请从流式块中解析 shannon_events 字段： 
import json
import httpx

def stream_with_events(query: str, model: str = "shannon-deep-research"):
    response = httpx.post(
        "http://localhost:8080/v1/chat/completions",
        headers={
            "Content-Type": "application/json",
            "Authorization": "Bearer sk_your_api_key",
        },
        json={
            "model": model,
            "messages": [{"role": "user", "content": query}],
            "stream": True,
        },
        timeout=None,
    )

    for line in response.iter_lines():
        if not line.startswith("data: "):
            continue
        data = line[6:]
        if data == "[DONE]":
            break

        chunk = json.loads(data)

        # 打印内容增量
        delta = chunk["choices"][0].get("delta", {})
        if delta.get("content"):
            print(delta["content"], end="", flush=True)

        # 打印 Shannon 智能体事件
        for event in chunk.get("shannon_events", []):
            print(f"\n  [{event['type']}] {event.get('message', '')}")

stream_with_events("研究量子计算的最新发展")

​
心跳和保活

在流式传输期间，Shannon 每 30 秒发送 SSE 注释行（: keepalive）以保持连接活跃。符合规范的 SSE 客户端会自动忽略这些注释。这可以防止负载均衡器和代理在长时间运行的研究任务中关闭空闲连接。

​
限制

以下 OpenAI API 功能不受支持：
功能状态
函数调用 / tools不支持
视觉 / 图片输入不支持（仅文本内容）
音频输入/输出不支持
嵌入 API（/v1/embeddings）不可用
微调 API不可用
response_format（JSON 模式）不支持
logprobs不支持
seed不支持
n > 1（多个补全）不支持
messages[].content 字段仅接受纯文本字符串。不支持多部分内容（包含 image_url 对象的数组）。

​
与标准 OpenAI API 的差异

方面OpenAI APIShannon OpenAI 兼容 API
模型GPT-4、GPT-3.5 等shannon-chat、shannon-deep-research 等
处理方式单次 LLM 调用多智能体编排、工具使用、研究
延迟秒级秒到分钟（取决于模型/策略）
流式事件仅内容内容 + shannon_events 智能体生命周期
会话管理非内置X-Session-ID 头，服务端上下文
速率限制按组织按 API 密钥、按模型
结束原因stop、length、tool_calls、content_filter仅 stop

​
相关内容

提交任务（原生 API）

具有完整功能的 Shannon 任务提交

事件流式传输

Shannon 原生 SSE 和 WebSocket 流式传输

事件类型参考

Shannon 事件类型的完整列表

Python SDK

Shannon 原生 Python 客户端