1.4.x 패치로 ChatFireworks 설정이 달라졌다

8일 만에 세 번의 패치: langchain-fireworks는 2026년 5월 20일부터 27일 사이에 1.3.x에서 1.4.2로 업데이트되었으며 , SDK 마이그레이션, 타입 지정 컨텍스트 오버플로 예외, 더 명확한 재시도 소유권 구조, 그리고 이전 버전에서 크로스-프로바이더 파이프라인을 조용히 망가뜨렸던 직렬화 수정 사항을 제공했습니다. 이 튜토리얼에서는 변경된 내용을 분석하고, 툴 호출이 포함된 ChatFireworks 인스턴스를 실행하는 방법을 안내합니다.

1.4.0–1.4.2 상세 해설: 의존성 업그레이드, 직렬화 정리, 재시도 재연결

1.4.x 시리즈는 세 번의 빠른 릴리스에 걸쳐 일관되게 진행된 강화 스프린트입니다. 버전 1.4.0 (5월 20일) 은 통합 패키지를 fireworks-ai 0.x에서 1.x 프리릴리스 라인으로 마이그레이션하고(PR #37581) FireworksContextOverflowError를 도입했습니다 — 프롬프트가 모델의 컨텍스트 윈도우를 초과할 때 발생하던 raw BadRequestError를 감싸는 타입 지정 래퍼입니다. 버전 1.4.1 (5월 21일) 은 재시도 소유권을 LangChain의 데코레이터 레이어로 완전히 이전했습니다: max_retries=2가 이제 기본값이며(PR #37602), 이중 계산을 방지하기 위해 하위 HTTP 클라이언트는 max_retries=0으로 초기화됩니다. 버전 1.4.2 (5월 27일) 는 영향 범위가 가장 넓습니다: Fireworks wire API로 전송하기 전에 비-wire 키 — 텍스트 블록에 붙는 Anthropic의 index, tool_use 블록에 붙는 LangChain 내부 caller — 를 제거합니다(PR #37714). 1.4.2 이전에는 이 추가 키들이 멀티-프로바이더 파이프라인에서 유효성 검사 오류를 발생시켰습니다.

빠른 답변: langchain-fireworks 1.4.2 (2026년 5월 27일)는 Fireworks API로 전송하기 전에 비-wire 콘텐츠 파트 키(index, caller)를 제거하여 크로스-프로바이더 유효성 검사 오류를 수정합니다. 1.4.1의 재시도 재연결(max_retries=2 기본값, HTTP 클라이언트는 max_retries=0) 및 1.4.0의 fireworks-ai 1.x 업그레이드와 결합하면, 이 패치 시퀀스는 멀티-프로바이더 파이프라인에서 ChatFireworks를 훨씬 더 안정적으로 만들어 줍니다.

"비-wire 키 — Anthropic 텍스트 블록의 index, LangChain tool_use 블록의 caller 등 — 를 Fireworks wire API로 전송하기 전에 제거합니다; 이전에는 이러한 키가 크로스-프로바이더 파이프라인에서 유효성 검사 오류를 발생시켰습니다." — PR #37714 설명, langchain-ai/langchain

시작 전 확인사항: Python 3.10+, fireworks-ai 1.x 알파, Fireworks 계정

Python 3.10 이상 과 Fireworks API 키가 필요합니다 — app.fireworks.ai/login에서 발급받으세요. 한 가지 의존성 주의 사항은 별도로 설명할 만큼 중요합니다.

fireworks-ai 1.x는 아직 알파 단계입니다. 2026년 5월 말 기준 최신 프리릴리스는 1.2.0a73이며 , 마지막 안정 릴리스는 2025년 10월의 0.19.20입니다 . 프로덕션 환경에서는 >=1.0 같은 범위 대신 fireworks-ai==1.2.0a73처럼 정확한 알파 버전으로 고정하세요. 알파 빌드는 semver 메이저 버전 업 신호 없이도 패치 버전 사이에서 호환성을 깨는 API 변경을 도입할 수 있습니다.

ChatFireworks 설치·인스턴스 생성·호출: 단계별 가이드

ChatFireworks는 Fireworks 호스팅 모델을 위한 기본 BaseChatModel 인터페이스입니다 . 모델 식별자는 accounts/fireworks/models/<slug> 패턴을 따릅니다. 다음 다섯 단계를 따라 설정을 완료하세요.

사용량 추적과 함께 스트리밍. 1.2.0부터(1.4.2에도 이어짐) stream_usage=True를 설정하면 stream_options.include_usage가 활성화됩니다 . 최종 청크는 이제 조용히 삭제되지 않고 usage_metadata가 포함된 AIMessageChunk로 반환됩니다:

for chunk in llm.stream("Tell me a joke"):
    print(chunk.content, end="", flush=True)
    if chunk.usage_metadata:
        print(f"\nTokens used: {chunk.usage_metadata}")

호출. .invoke()는 AIMessage를 반환하며, .content는 텍스트 문자열입니다:

messages = [
    ("system", "You are a helpful assistant that translates English to French."),
    ("human", "I love programming."),
]
ai_msg = llm.invoke(messages)
print(ai_msg.content)  # "J'adore la programmation."

인스턴스 생성.

from langchain_fireworks import ChatFireworks

llm = ChatFireworks(
    model="accounts/fireworks/models/llama-v3p1-8b-instruct",
    temperature=0,
    max_retries=2,       # LangChain decorator layer; HTTP client uses max_retries=0
    stream_usage=True,   # include token counts in streamed chunks
)

인증 정보. API 키를 환경 변수로 내보내거나 생성자에 api_key=를 직접 전달하세요. 환경 변수 방식을 권장합니다:

export FIREWORKS_API_KEY='fw_...'

설치. 1.4.2로 업그레이드하고 확인합니다:

pip install -qU langchain-fireworks
pip show langchain-fireworks   # expect: Version: 1.4.2

또는 uv 사용 시: uv add langchain-fireworks

미리 알아야 할 함정: 알파 버전 고정, 크로스 프로바이더 메시지, 재시도 소유권

1.4.x 업그레이드 시 신중하게 다뤄야 할 네 가지 영역:

• 알파 불안정성. fireworks-ai를 범위 지정 대신 정확한 알파 버전으로 고정하세요 — 예: fireworks-ai==1.2.0a73 . 알파 빌드는 semver 신호 없이 패치 버전 간 호환성을 깨는 API 변경을 도입할 수 있습니다. 업그레이드 전에 통합 테스트를 실행하세요.
• 크로스 프로바이더 파이프라인. 1.4.2 직렬화 수정은 wire API 전송 전에 index와 caller 키를 자동으로 제거합니다. 1.4.2 이전 유효성 검사 오류를 우회하기 위해 메시지를 수동으로 정제하고 있었다면, 업그레이드 후 해당 우회 코드를 제거하세요 — 이중 제거는 무해하지만 파이프라인에 노이즈를 추가합니다.
• 재시도 소유권. ChatFireworks의 max_retries는 LangChain 데코레이터 레이어만 제어합니다. 내부 fireworks.Fireworks() HTTP 클라이언트는 설계상 max_retries=0으로 초기화됩니다 . 이를 통해 각 시도가 run_manager.on_retry에 표시되고 이중 계산을 방지합니다. HTTP 클라이언트 수준에서 max_retries를 재정의하려 하지 마세요.
• 이미지 입력은 지원되지 않습니다. ChatFireworks는 1.4.2 기준으로 멀티모달(이미지) 메시지 콘텐츠에 대해 오류를 발생시킵니다. 비전 워크플로를 이 통합으로 라우팅하기 전에 기능 매트릭스를 확인하세요 — 비전 작업에는 다른 LangChain 채팅 모델을 사용하세요.

설정 확장하기: 도구 호출, 구조화된 출력, 비동기

기본 호출이 작동하면, 프로덕션 통합을 위한 가장 유용한 다음 단계는 도구 호출, 구조화된 출력, 명시적 오류 처리입니다. 아래 코드 스니펫은 예시로 — 실제 API에서 실행된 것이 아니지만 — bind_tools()의 현재 문서화된 인터페이스를 반영합니다:

from typing import Annotated
import os

try:
    from langchain_core.tools import tool
    from langchain_fireworks import ChatFireworks
except ImportError as e:
    print(f"missing dependency: {e.name}")
    raise SystemExit(1)

if not os.environ.get("FIREWORKS_API_KEY"):
    print("Set FIREWORKS_API_KEY to run this ChatFireworks example.")
    raise SystemExit(1)


@tool
def multiply(
    a: Annotated[int, "first factor"],
    b: Annotated[int, "second factor"],
) -> int:
    """Multiply two integers."""
    return a * b


llm = ChatFireworks(model="accounts/fireworks/models/llama-v3p1-8b-instruct")
llm_with_tools = llm.bind_tools([multiply])
response = llm_with_tools.invoke("What is 6 times 7? Use the tool.")

print(response.content)
print(response.tool_calls)

도구 호출 외에도 이 통합은 다음을 지원합니다:

• 구조화된 출력. llm.with_structured_output(MyPydanticModel)은 모델 응답에서 결정론적 JSON 추출을 위해 Pydantic v2 스키마와 함께 작동합니다.
• 비동기. asyncio 컨텍스트용 llm.ainvoke(messages); 비동기 스트리밍용 llm.astream(messages). 인터페이스는 동기 API와 완전히 동일합니다.
• 컨텍스트 오버플로 처리. 원시 HTTP 오류가 전파되도록 두는 대신, try/except FireworksContextOverflowError(1.4.0에 추가)로 호출을 감싸 프롬프트 초과 조건을 명시적으로 처리하세요:

from langchain_fireworks import ChatFireworks, FireworksContextOverflowError

try:
    result = llm.invoke(long_messages)
except FireworksContextOverflowError:
    # truncate context, switch to a larger-window model, or summarize before retrying
    result = fallback_llm.invoke(summarize(long_messages))

자주 묻는 질문

fireworks-ai 1.x, 프로덕션에 써도 될까요?

아직 이릅니다. 1.x 시리즈는 현재 활성 알파 단계로, 2026년 5월 말 기준 최신 릴리스는 1.2.0a73 이며, 마지막 안정 릴리스는 2025년 10월의 0.19.20입니다 . 프로덕션에 배포한다면 정확한 알파 버전으로 고정하고 업그레이드마다 통합 테스트를 실행하세요. >=1.0 같은 semver 범위로 부동(floating)하면 알파 패치 사이에 조용한 호환성 파괴 변경이 유입될 수 있습니다.

1.4.2의 직렬화 스트립, 실제로 뭘 고치나요?

여러 프로바이더에서 메시지를 조합할 때 콘텐츠 파트 딕셔너리에 프로바이더 고유 키가 섞일 수 있습니다. Anthropic 텍스트 블록은 index 키를, LangChain 내부 tool_use 블록은 caller 키를 붙입니다. 1.4.2 이전에는 이 여분의 키들이 Fireworks 와이어 API까지 그대로 전달되어 유효성 검사 오류를 일으켰습니다. 버전 1.4.2는 Fireworks SDK 자체 TypedDict에서 파생한 허용 목록으로 구축된 정제 함수를 도입해, 모든 API 호출 전에 비(非)와이어 키를 제거합니다. 기존 파이프라인 업그레이드는 투명하게 이루어지며, 유일하게 눈에 띄는 변화는 해당 유효성 검사 오류가 사라진다는 점입니다.

1.4.x의 재시도 로직, 이전 버전과 무엇이 다른가요?

1.4.1부터 재시도 소유권은 전적으로 LangChain의 데코레이터 레이어에 있습니다. 내부 fireworks.Fireworks() HTTP 클라이언트는 max_retries=0으로 초기화되어 자체적으로 재시도를 수행하지 않습니다. ChatFireworks의 기본값 max_retries=2는 LangChain 경로를 통해 최대 두 번 재시도하며, 각 재시도는 run_manager.on_retry 콜백에서 확인할 수 있습니다. 버전 1.4.1은 이전 버전에서 재시도하지 않던 순수 APIConnectionError 조건에 대한 재시도 커버리지도 추가했습니다.

ChatFireworks에서 이미지나 멀티모달 입력을 처리할 수 있나요?

아닙니다. 1.4.2 기준으로 이미지 입력은 지원되지 않으며 오류가 발생합니다. ChatFireworks는 텍스트 입력, 도구 호출, 구조화된 출력, 스트리밍, logprobs를 지원하지만 비전은 지원하지 않습니다. 멀티모달 워크플로의 경우 이미지 콘텐츠 블록을 지원하는 LangChain 채팅 모델 통합을 사용하고, 텍스트 전용 단계에만 Fireworks로 라우팅하세요.

FireworksContextOverflowError란? 언제 발생하나요?

FireworksContextOverflowError는 1.4.0에서 추가된 타입 지정 래퍼로, 프롬프트가 모델의 컨텍스트 윈도우를 초과할 때 반환되는 원시 BadRequestError를 감쌉니다. 1.4.0 이전에는 이 조건이 타입 없는 HTTP 오류로 나타나 감지하려면 문자열 매칭이 필요했습니다. 이를 명시적으로 잡으면 폴백으로 깔끔하게 분기할 수 있습니다: 컨텍스트 잘라내기, 더 큰 윈도우를 가진 모델로 전환, 또는 재시도 전 대화 요약.

다음 단계 가이드

1.4.2를 설치하고 invoke 경로가 정상 동작한다면, 이제 이렇게 이어가세요: JSON 추출 사용 사례에 with_structured_output()을 연결하고, 컨텍스트 한계 근처에서 운영 중이라면 호출 지점에 FireworksContextOverflowError 처리를 추가하며, 1.4.2 직렬화 수정이 특정 메시지 형태를 커버하는지 확인하기 위해 크로스 프로바이더 메시지 왕복(Anthropic 또는 OpenAI → Fireworks)을 명시적으로 테스트하세요. fireworks-ai 0.x에서 마이그레이션 중이라면 1.4.0 SDK 업그레이드가 호환성 차이를 드러낼 가능성이 가장 높습니다 — 프로덕션 의존성을 업그레이드하기 전에 업데이트된 통합 문서와 API 레퍼런스를 검토하세요.

Fireworks LangChain 통합 개요에서 사용 가능한 모델 슬러그와 티어 옵션을 확인할 수 있습니다. service_tier, logprobs, timeout을 포함한 전체 파라미터 목록은 GitHub 소스를 참조하세요.

최종 업데이트: 2026-05-31. langchain-fireworks 1.4.2 (2026년 5월 27일 릴리스) 및 fireworks-ai 1.2.0a73 기준.