Enhance AssistantConfig and pipeline for FastGPT integration

- Add new fields in AssistantConfig for FastGPT connection details, including `fastgpt_api_url`, `fastgpt_api_key`, and `fastgpt_app_id`. - Update the pipeline to utilize the new FastGPT configuration, ensuring proper integration with external services. - Introduce type handling for different assistant types, including support for realtime modes and external brain management. - Refactor frontend components to include hints for FastGPT configuration inputs, improving user guidance during setup.
2026-06-16 16:55:51 +08:00
parent 43cc188d85
commit 809b634420
13 changed files with 415 additions and 18 deletions
--- a/backend/services/brains/init.py
+++ b/backend/services/brains/init.py
@@ -0,0 +1,6 @@
+"""可插拔的「大脑」:把不同助手类型在运行时的差异收口到各自的 Brain 实现。"""
+
+from services.brains.base import Brain, BrainSpec
+from services.brains.registry import SPECS, build_brain
+
+__all__ = ["Brain", "BrainSpec", "SPECS", "build_brain"]
--- a/backend/services/brains/base.py
+++ b/backend/services/brains/base.py
@@ -0,0 +1,46 @@
+"""「大脑」抽象:把不同助手类型(prompt/workflow/fastgpt/…)在运行时的差异收口。
+
+cascade 管线骨架对所有类型一致(STT → LLM 槽 → TTS),变化的只有:
+  - 谁产出助手文本(LLM 槽里塞什么)——build_llm
+  - 开场白来源(静态 / 外部异步拉取)——greeting
+  - 对话上下文归谁维护——spec.owns_context
+  - 是否支持 realtime——spec.supported_runtime_modes
+
+阶段 1 只抽到「够 fastgpt 用」的程度;workflow 编排仍内联在 pipeline.py,
+待阶段 2 再搬进 WorkflowBrain 收口。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Protocol, runtime_checkable
+
+from models import AssistantConfig
+from pipecat.processors.aggregators.llm_context import LLMContext
+from pipecat.processors.frame_processor import FrameProcessor
+
+
+@dataclass(frozen=True)
+class BrainSpec:
+    """类型元数据。单一来源,供运行时门控与上下文归属决策复用。"""
+
+    type: str
+    supported_runtime_modes: frozenset[str]
+    # True:由本服务维护 LLMContext(prompt/workflow);
+    # False:上下文/知识库/工具由外部服务端接管(fastgpt/dify),本地不写 context。
+    owns_context: bool
+
+
+@runtime_checkable
+class Brain(Protocol):
+    """每通电话 new 一个实例(可持有 chatId / 当前节点等会话状态)。"""
+
+    spec: BrainSpec
+
+    async def greeting(self, cfg: AssistantConfig) -> str:
+        """开场白。内部类型通常直接用 cfg.greeting;外部类型异步拉取后端配置。"""
+        ...
+
+    def build_llm(self, cfg: AssistantConfig, context: LLMContext) -> FrameProcessor:
+        """返回丢进管线 LLM 槽位的帧处理器(标准 LLMService 或外部托管的伪 LLM)。"""
+        ...
--- a/backend/services/brains/fastgpt_brain.py
+++ b/backend/services/brains/fastgpt_brain.py
@@ -0,0 +1,67 @@
+"""FastGPT 大脑:外部托管,context/KB/tools 全在 FastGPT 服务端。
+
+cascade-only(realtime 不兼容外部大脑)。每通电话持有一个稳定 chatId:
+greeting(get_chat_init)与后续每轮推理共用它,保证服务端上下文连续。
+"""
+
+from __future__ import annotations
+
+from typing import Any
+from uuid import uuid4
+
+from fastgpt_client import AsyncChatClient
+from loguru import logger
+from models import AssistantConfig
+from pipecat.processors.aggregators.llm_context import LLMContext
+from pipecat.processors.frame_processor import FrameProcessor
+
+from services.brains.base import BrainSpec
+from services.brains.fastgpt_llm import FastGPTLLMService, normalize_base_url
+
+
+def _extract_welcome(payload: Any) -> str:
+    """从 get_chat_init 响应里取开场白(welcomeText),多层兜底。"""
+    if not isinstance(payload, dict):
+        return ""
+    data = payload.get("data") if isinstance(payload.get("data"), dict) else payload
+    app = data.get("app") if isinstance(data.get("app"), dict) else {}
+    chat_config = app.get("chatConfig") if isinstance(app.get("chatConfig"), dict) else {}
+    for value in (
+        chat_config.get("welcomeText"),
+        app.get("welcomeText"),
+        data.get("welcomeText"),
+        data.get("opener"),
+        app.get("opener"),
+    ):
+        if isinstance(value, str) and value.strip():
+            return value.strip()
+    return ""
+
+
+class FastGPTBrain:
+    def __init__(self):
+        self.spec = BrainSpec(
+            type="fastgpt",
+            supported_runtime_modes=frozenset({"pipeline"}),
+            owns_context=False,
+        )
+        self._chat_id = uuid4().hex
+
+    async def greeting(self, cfg: AssistantConfig) -> str:
+        """优先用 FastGPT 后台配置的开场白;无 app_id 或取不到时回退 cfg.greeting。"""
+        if not cfg.fastgpt_app_id:
+            return cfg.greeting
+        try:
+            client = AsyncChatClient(
+                api_key=cfg.fastgpt_api_key,
+                base_url=normalize_base_url(cfg.fastgpt_api_url),
+            )
+            response = await client.get_chat_init(cfg.fastgpt_app_id, self._chat_id)
+            welcome = _extract_welcome(response.json())
+            return welcome or cfg.greeting
+        except Exception as exc:  # noqa: BLE001 - 拉取失败不应阻断通话
+            logger.warning(f"FastGPT get_chat_init 失败,回退 cfg.greeting: {exc}")
+            return cfg.greeting
+
+    def build_llm(self, cfg: AssistantConfig, context: LLMContext) -> FrameProcessor:
+        return FastGPTLLMService(cfg, chat_id=self._chat_id)
--- a/backend/services/brains/fastgpt_llm.py
+++ b/backend/services/brains/fastgpt_llm.py
@@ -0,0 +1,161 @@
+"""FastGPT 作为 pipecat LLM 槽位。
+
+与普通 LLM 的关键不同:context / 知识库 / 工具全在 FastGPT 服务端,靠 chatId
+维持会话。所以本服务只发「最后一条 user 文本」+ 稳定 chatId,把流式 answer
+事件转成 LLMTextFrame 交给下游 TTS;不消费/不依赖本地 LLMContext 的历史。
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from fastgpt_client import AsyncChatClient, aiter_stream_events
+from loguru import logger
+from models import AssistantConfig
+
+from pipecat.frames.frames import (
+    Frame,
+    LLMContextFrame,
+    LLMFullResponseEndFrame,
+    LLMFullResponseStartFrame,
+    LLMTextFrame,
+)
+from pipecat.processors.frame_processor import FrameDirection
+from pipecat.services.llm_service import LLMService
+from pipecat.services.settings import LLMSettings
+
+# 承载回复文本的事件种类。detail=False 时 FastGPT 走 OpenAI 兼容流,文本以裸
+# data: 块下发(无 event 名 → kind="data");detail=True / 旧版则用 answer/fastAnswer。
+_ANSWER_KINDS = {"data", "answer", "fastAnswer"}
+
+# SDK 会自动在 base_url 后拼 /api/v1/chat/completions(并去掉末尾 /api)。
+# 用户常把「完整接口地址」填进 api_url,这里剥掉这些后缀,归一成主机根地址,
+# 避免路径重复导致 404。
+_ENDPOINT_SUFFIXES = (
+    "/api/v1/chat/completions",
+    "/v1/chat/completions",
+    "/chat/completions",
+)
+
+
+def normalize_base_url(url: str) -> str:
+    base = (url or "").strip().rstrip("/")
+    for suffix in _ENDPOINT_SUFFIXES:
+        if base.endswith(suffix):
+            base = base[: -len(suffix)]
+            break
+    return base or "http://localhost:3000"
+
+
+def _last_user_text(messages: list[dict]) -> str:
+    """取最近一条 user 消息的纯文本(兼容多模态分片)。"""
+    for message in reversed(messages or []):
+        if message.get("role") != "user":
+            continue
+        content = message.get("content")
+        if isinstance(content, str):
+            return content
+        if isinstance(content, list):
+            return "".join(
+                str(part.get("text") or "")
+                for part in content
+                if isinstance(part, dict)
+            )
+    return ""
+
+
+def _event_text(data: Any) -> str:
+    """从一个流事件里取增量文本。
+
+    兼容两种形态(对齐 SDK examples 的解析):
+      - 直接 text 字段(answer/fastAnswer 详情流);
+      - OpenAI 兼容块 choices[0].delta.content / message.content(detail=False)。
+    """
+    if not isinstance(data, dict):
+        return ""
+
+    text = data.get("text")
+    if isinstance(text, str) and text:
+        return text
+
+    choices = data.get("choices")
+    if not isinstance(choices, list) or not choices:
+        return ""
+    first = choices[0] if isinstance(choices[0], dict) else {}
+
+    delta = first.get("delta")
+    if isinstance(delta, dict):
+        content = delta.get("content")
+        if isinstance(content, str) and content:
+            return content
+
+    message = first.get("message")
+    if isinstance(message, dict):
+        content = message.get("content")
+        if isinstance(content, str) and content:
+            return content
+
+    return ""
+
+
+class FastGPTLLMService(LLMService):
+    """包 FastGPT OpenAPI 的伪 LLM 服务。"""
+
+    def __init__(self, cfg: AssistantConfig, chat_id: str):
+        # FastGPT 自管 model/温度等参数,这里把所有 LLM 设置初始化为 None,
+        # 满足基类 validate_complete(否则启动期会报 NOT_GIVEN)。
+        super().__init__(
+            settings=LLMSettings(
+                model=None,
+                system_instruction=None,
+                temperature=None,
+                max_tokens=None,
+                top_p=None,
+                top_k=None,
+                frequency_penalty=None,
+                presence_penalty=None,
+                seed=None,
+                filter_incomplete_user_turns=None,
+                user_turn_completion_config=None,
+            )
+        )
+        self._chat_id = chat_id
+        self._base_url = normalize_base_url(cfg.fastgpt_api_url)
+        self._client = AsyncChatClient(
+            api_key=cfg.fastgpt_api_key,
+            base_url=self._base_url,
+        )
+
+    async def process_frame(self, frame: Frame, direction: FrameDirection):
+        await super().process_frame(frame, direction)
+
+        if not isinstance(frame, LLMContextFrame):
+            await self.push_frame(frame, direction)
+            return
+
+        user_text = _last_user_text(frame.context.get_messages())
+        if not user_text:
+            return
+
+        await self.push_frame(LLMFullResponseStartFrame())
+        try:
+            response = await self._client.create_chat_completion(
+                messages=[{"role": "user", "content": user_text}],
+                stream=True,
+                chatId=self._chat_id,
+                detail=False,
+            )
+            async for event in aiter_stream_events(response):
+                if event.kind in _ANSWER_KINDS:
+                    text = _event_text(event.data)
+                    if text:
+                        await self.push_frame(LLMTextFrame(text))
+                elif event.kind == "error":
+                    logger.error(f"FastGPT 流式错误: {event.data}")
+        except Exception as exc:  # noqa: BLE001 - 单轮失败不应中断通话
+            logger.error(
+                f"FastGPT 调用失败: {exc} "
+                f"(base_url={self._base_url},拼接后应为 {self._base_url}/api/v1/chat/completions)"
+            )
+        finally:
+            await self.push_frame(LLMFullResponseEndFrame())
--- a/backend/services/brains/internal_brain.py
+++ b/backend/services/brains/internal_brain.py
@@ -0,0 +1,37 @@
+"""内部 LLM 大脑:prompt 与 workflow。
+
+二者都用本地维护的 LLMContext + OpenAI 兼容 LLM,支持 cascade 与 realtime。
+workflow 的图编排(切提示/转移工具/node-active)阶段 1 仍内联在 pipeline.py,
+这里只负责提供 LLM 槽位与元数据,行为与改造前完全一致。
+"""
+
+from __future__ import annotations
+
+from models import AssistantConfig
+from pipecat.processors.aggregators.llm_context import LLMContext
+from pipecat.processors.frame_processor import FrameProcessor
+
+from services.brains.base import BrainSpec
+
+_CASCADE_AND_REALTIME = frozenset({"pipeline", "realtime"})
+
+
+class InternalBrain:
+    """prompt / workflow 共用。"""
+
+    def __init__(self, brain_type: str):
+        self.spec = BrainSpec(
+            type=brain_type,
+            supported_runtime_modes=_CASCADE_AND_REALTIME,
+            owns_context=True,
+        )
+
+    async def greeting(self, cfg: AssistantConfig) -> str:
+        # 内部类型的开场白由 pipeline.py 现有逻辑(workflow 起始节点 / cfg.greeting)决定,
+        # 该方法仅为满足 Brain 协议,实际不在内部路径上被调用。
+        return cfg.greeting
+
+    def build_llm(self, cfg: AssistantConfig, context: LLMContext) -> FrameProcessor:
+        from services.pipecat.service_factory import create_llm
+
+        return create_llm(cfg)
--- a/backend/services/brains/registry.py
+++ b/backend/services/brains/registry.py
@@ -0,0 +1,25 @@
+"""类型 → Brain 工厂。新增一种大脑 = 加一个 brain 文件 + 在此注册一行。"""
+
+from __future__ import annotations
+
+from models import AssistantConfig
+
+from services.brains.base import Brain, BrainSpec
+from services.brains.fastgpt_brain import FastGPTBrain
+from services.brains.internal_brain import InternalBrain
+
+# 各类型的元数据(供 schema 校验 / realtime 门控复用,无需实例化 Brain)。
+SPECS: dict[str, BrainSpec] = {
+    "prompt": InternalBrain("prompt").spec,
+    "workflow": InternalBrain("workflow").spec,
+    "fastgpt": FastGPTBrain().spec,
+}
+
+
+def build_brain(cfg: AssistantConfig) -> Brain:
+    """按 cfg.type 构造每通电话的 Brain 实例(未知类型回退 prompt)。"""
+    if cfg.type == "fastgpt":
+        return FastGPTBrain()
+    if cfg.type in ("prompt", "workflow"):
+        return InternalBrain(cfg.type)
+    return InternalBrain("prompt")
--- a/backend/services/config_resolver.py
+++ b/backend/services/config_resolver.py
@@ -61,6 +61,7 @@ async def resolve_runtime_config(

    return AssistantConfig(
        name=assistant.name,
+        type=assistant.type,
        greeting=assistant.greeting,
        # prompt 现在是真列;外部类型由其平台编排,这里给个兜底
        prompt=assistant.prompt or "你是一个有帮助的助手。",
@@ -68,6 +69,10 @@ async def resolve_runtime_config(
        enableInterrupt=assistant.enable_interrupt,
        # workflow 图:仅 workflow 类型非空,引擎据此启用图驱动对话
        graph=(assistant.graph or {}) if assistant.type == "workflow" else {},
+        # 外部托管类型连接信息(DB 存真 key,直接注入)
+        fastgpt_api_url=assistant.api_url,
+        fastgpt_api_key=assistant.api_key,
+        fastgpt_app_id=assistant.app_id,
        # 模型/音色:模型资源中的配置优先
        model=str(_value(llm_resource, "modelId", "")),
        asr=str(_value(stt_resource, "modelId", "")),
--- a/backend/services/pipecat/pipeline.py
+++ b/backend/services/pipecat/pipeline.py
@@ -11,7 +11,12 @@ from uuid import uuid4
 import config
 from loguru import logger
 from models import AssistantConfig
-from services.pipecat.service_factory import create_realtime_service, create_services
+from services.brains import build_brain
+from services.pipecat.service_factory import (
+    create_realtime_service,
+    create_stt,
+    create_tts,
+)
 from services.workflow_engine import WorkflowEngine

 from pipecat.adapters.schemas.function_schema import FunctionSchema
@@ -207,13 +212,23 @@ async def run_pipeline(transport, cfg: AssistantConfig) -> None:
                   只要有 .input() / .output() / event_handler 即可。
        cfg:       助手配置(随请求内联传入)。
    """
-    logger.info(f"启动管线: assistant={cfg.name} mode={cfg.runtimeMode}")
+    logger.info(f"启动管线: assistant={cfg.name} type={cfg.type} mode={cfg.runtimeMode}")
+
+    # 大脑:按类型决定 LLM 槽/开场白/上下文归属。每通电话一个实例(可持会话状态)。
+    brain = build_brain(cfg)
+    if (
+        cfg.runtimeMode == "realtime"
+        and "realtime" not in brain.spec.supported_runtime_modes
+    ):
+        logger.warning(f"类型 {cfg.type} 不支持 realtime,回退 cascade")
+        cfg.runtimeMode = "pipeline"

    if cfg.runtimeMode == "realtime":
        await run_realtime_pipeline(transport, cfg)
        return

-    stt, llm, tts = create_services(cfg)
+    stt = create_stt(cfg)
+    tts = create_tts(cfg)

    # ---- workflow 图引擎(可选)----
    # 有节点图时按图驱动:开场白/系统提示来自起始节点,每轮回复后按条件路由。
@@ -240,11 +255,17 @@ async def run_pipeline(transport, cfg: AssistantConfig) -> None:
        logger.info(
            f"工作流模式启用: 起始节点={engine.name(wf_state['current'])}"
        )
-    else:
+    elif brain.spec.owns_context:
        greeting = cfg.greeting
        system_content = cfg.prompt
+    else:
+        # 外部托管(fastgpt 等):开场白来自对方后台,系统提示/上下文不归我们维护
+        greeting = await brain.greeting(cfg)
+        system_content = ""

    context = LLMContext(messages=[{"role": "system", "content": system_content}])
+    # LLM 槽由大脑提供:内部类型=OpenAI 兼容服务;fastgpt=包 SDK 的伪 LLM。
+    llm = brain.build_llm(cfg, context)
    user_aggregator = LLMUserAggregator(
        context,
        params=LLMUserAggregatorParams(
@@ -539,7 +560,9 @@ async def run_pipeline(transport, cfg: AssistantConfig) -> None:
    @transport.event_handler("on_client_connected")
    async def on_client_connected(_transport, _client):
        if greeting:
-            context.add_message({"role": "assistant", "content": greeting})
+            # 外部托管类型的上下文由对方服务端维护,开场白不写入本地 context
+            if brain.spec.owns_context:
+                context.add_message({"role": "assistant", "content": greeting})
            await worker.queue_frame(TTSSpeakFrame(greeting, append_to_context=False))
        # 工作流:点亮当前(开始)节点。开始节点即首个会话节点。
        if workflow_active:
--- a/backend/services/pipecat/service_factory.py
+++ b/backend/services/pipecat/service_factory.py
@@ -132,16 +132,6 @@ def create_tts(cfg: AssistantConfig):
    )


-def create_services(cfg: AssistantConfig):
-    logger.info(
-        f"创建服务: stt={cfg.stt_interface_type}/{cfg.asr or config.STT_MODEL} "
-        f"llm={cfg.model or config.LLM_MODEL} "
-        f"tts={cfg.tts_interface_type}/{cfg.tts_model or config.TTS_MODEL} "
-        f"voice={cfg.voice or config.TTS_VOICE}"
-    )
-    return create_stt(cfg), create_llm(cfg), create_tts(cfg)
-
-
 def create_realtime_service(cfg: AssistantConfig):
    """Create a speech-to-speech service that owns STT, LLM, and TTS."""
    if cfg.realtime_interface_type == "stepfun-realtime":