Alpha Notice: These docs cover the v1-alpha release. Content is incomplete and subject to change.For the latest stable version, see the current LangGraph Python or LangGraph JavaScript docs.
- 그래프 상태 스트리밍 —
updates
및values
모드로 상태 업데이트/값을 가져옵니다. - 서브그래프 출력 스트리밍 — 부모 그래프와 중첩된 서브그래프 모두의 출력을 포함합니다.
- LLM 토큰 스트리밍 — 노드, 서브그래프 또는 도구 내 어디서든 토큰 스트림을 캡처합니다.
- 커스텀 데이터 스트리밍 — 도구 함수에서 직접 커스텀 업데이트 또는 진행 상황 신호를 전송합니다.
- 여러 스트리밍 모드 사용 —
values
(전체 상태),updates
(상태 변경사항),messages
(LLM 토큰 + 메타데이터),custom
(임의의 사용자 데이터) 또는debug
(상세한 추적) 중에서 선택합니다.
지원되는 스트림 모드
다음 스트림 모드 중 하나 이상을 리스트로stream()
또는 astream()
메서드에 전달합니다:
모드 | 설명 |
---|---|
values | 그래프의 각 단계 후 상태의 전체 값을 스트리밍합니다. |
updates | 그래프의 각 단계 후 상태에 대한 업데이트를 스트리밍합니다. 동일한 단계에서 여러 업데이트가 발생하면 (예: 여러 노드가 실행됨), 해당 업데이트는 개별적으로 스트리밍됩니다. |
custom | 그래프 노드 내부에서 커스텀 데이터를 스트리밍합니다. |
messages | LLM이 호출되는 모든 그래프 노드에서 2-튜플 (LLM 토큰, 메타데이터)을 스트리밍합니다. |
debug | 그래프 실행 전반에 걸쳐 가능한 한 많은 정보를 스트리밍합니다. |
기본 사용 예제
LangGraph 그래프는 스트리밍 출력을 이터레이터로 생성하기 위해.stream()
(동기) 및 .astream()
(비동기) 메서드를 제공합니다.
확장 예제: 업데이트 스트리밍
확장 예제: 업데이트 스트리밍
여러 모드 스트리밍
stream_mode
매개변수에 리스트를 전달하여 여러 모드를 동시에 스트리밍할 수 있습니다.
스트리밍되는 출력은 (mode, chunk)
튜플이 되며, 여기서 mode
는 스트림 모드의 이름이고 chunk
는 해당 모드에서 스트리밍된 데이터입니다.
그래프 상태 스트리밍
updates
및 values
스트림 모드를 사용하여 그래프 실행 시 상태를 스트리밍합니다.
updates
는 그래프의 각 단계 후 상태에 대한 업데이트를 스트리밍합니다.values
는 그래프의 각 단계 후 상태의 전체 값을 스트리밍합니다.
- updates
- values
각 단계 후 노드가 반환한 상태 업데이트만 스트리밍하려면 이 모드를 사용합니다. 스트리밍되는 출력에는 노드의 이름과 업데이트가 포함됩니다.
서브그래프 출력 스트리밍
스트리밍되는 출력에 서브그래프의 출력을 포함하려면, 부모 그래프의.stream()
메서드에서 subgraphs=True
로 설정할 수 있습니다. 이렇게 하면 부모 그래프와 모든 서브그래프의 출력이 스트리밍됩니다.
출력은 (namespace, data)
튜플로 스트리밍되며, 여기서 namespace
는 서브그래프가 호출되는 노드의 경로를 가진 튜플입니다. 예: ("parent_node:<task_id>", "child_node:<task_id>")
확장 예제: 서브그래프에서 스트리밍
확장 예제: 서브그래프에서 스트리밍
디버깅
debug
스트리밍 모드를 사용하여 그래프 실행 전반에 걸쳐 가능한 한 많은 정보를 스트리밍합니다. 스트리밍되는 출력에는 노드의 이름과 전체 상태가 포함됩니다.
LLM 토큰
messages
스트리밍 모드를 사용하여 노드, 도구, 서브그래프 또는 태스크를 포함한 그래프의 모든 부분에서 대규모 언어 모델(LLM) 출력을 토큰 단위로 스트리밍합니다.
messages
모드에서 스트리밍되는 출력은 (message_chunk, metadata)
튜플입니다:
message_chunk
: LLM에서 나온 토큰 또는 메시지 세그먼트입니다.metadata
: 그래프 노드 및 LLM 호출에 대한 세부 정보가 포함된 딕셔너리입니다.
LLM이 LangChain 통합으로 제공되지 않는 경우, custom
모드를 사용하여 출력을 스트리밍할 수 있습니다. 자세한 내용은 모든 LLM과 함께 사용을 참조하세요.
Python < 3.11에서 async 사용 시 수동 구성 필요
Python < 3.11에서 async 코드를 사용할 때는 적절한 스트리밍을 활성화하기 위해 명시적으로
RunnableConfig
를 ainvoke()
에 전달해야 합니다. 자세한 내용은 Python < 3.11에서 Async를 참조하거나 Python 3.11+로 업그레이드하세요.LLM 호출별 필터링
LLM 호출에tags
를 연결하여 LLM 호출별로 스트리밍된 토큰을 필터링할 수 있습니다.
확장 예제: 태그로 필터링
확장 예제: 태그로 필터링
노드별 필터링
특정 노드에서만 토큰을 스트리밍하려면,stream_mode="messages"
를 사용하고 스트리밍된 메타데이터의 langgraph_node
필드로 출력을 필터링합니다:
확장 예제: 특정 노드에서 LLM 토큰 스트리밍
확장 예제: 특정 노드에서 LLM 토큰 스트리밍
커스텀 데이터 스트리밍
LangGraph 노드 또는 도구 내부에서 커스텀 사용자 정의 데이터를 전송하려면 다음 단계를 따르세요:get_stream_writer()
를 사용하여 스트림 라이터에 액세스하고 커스텀 데이터를 발생시킵니다..stream()
또는.astream()
을 호출할 때stream_mode="custom"
으로 설정하여 스트림에서 커스텀 데이터를 가져옵니다. 여러 모드를 결합할 수 있지만 (예:["updates", "custom"]
), 적어도 하나는"custom"
이어야 합니다.
Python < 3.11에서 async에서
get_stream_writer()
사용 불가
Python < 3.11에서 실행되는 async 코드에서는 get_stream_writer()
가 작동하지 않습니다.
대신, 노드 또는 도구에 writer
매개변수를 추가하고 수동으로 전달하세요.
사용 예제는 Python < 3.11에서 Async를 참조하세요.- node
- tool
모든 LLM과 함께 사용
stream_mode="custom"
을 사용하여 모든 LLM API에서 데이터를 스트리밍할 수 있습니다 — 해당 API가 LangChain 채팅 모델 인터페이스를 구현하지 않더라도 말입니다.
이를 통해 자체 스트리밍 인터페이스를 제공하는 원시 LLM 클라이언트 또는 외부 서비스를 통합할 수 있어, LangGraph를 커스텀 설정에 매우 유연하게 사용할 수 있습니다.
확장 예제: 임의의 채팅 모델 스트리밍
확장 예제: 임의의 채팅 모델 스트리밍
특정 채팅 모델에 대한 스트리밍 비활성화
애플리케이션에서 스트리밍을 지원하는 모델과 지원하지 않는 모델을 혼합하여 사용하는 경우, 스트리밍을 지원하지 않는 모델에 대해 명시적으로 스트리밍을 비활성화해야 할 수 있습니다. 모델을 초기화할 때disable_streaming=True
로 설정합니다.
- init_chat_model
- chat model interface
Python < 3.11에서 Async
Python 버전 < 3.11에서는 asyncio 태스크가context
매개변수를 지원하지 않습니다.
이는 LangGraph가 컨텍스트를 자동으로 전파하는 기능을 제한하며, LangGraph의 스트리밍 메커니즘에 두 가지 주요 방식으로 영향을 미칩니다:
- 콜백이 자동으로 전파되지 않으므로, async LLM 호출(예:
ainvoke()
)에 명시적으로RunnableConfig
를 전달해야 합니다. - async 노드 또는 도구에서
get_stream_writer()
를 사용할 수 없습니다 —writer
인수를 직접 전달해야 합니다.
확장 예제: 수동 구성을 사용한 async LLM 호출
확장 예제: 수동 구성을 사용한 async LLM 호출
확장 예제: 스트림 라이터를 사용한 async 커스텀 스트리밍
확장 예제: 스트림 라이터를 사용한 async 커스텀 스트리밍