도구 사용(함수 호출)을 위한 인용
도구 사용(함수 호출)을 위한 인용
RAG용 Cohere Chat 엔드포인트가 생성하는 인용에 접근하고 활용하는 방법에 대한 가이드예요. 비스트리밍 및 스트리밍 모드 모두를 다룹니다 (API v2).
출처: 문서
본문
인용 접근(Accessing citations)
Chat 엔드포인트는 도구 사용 응답에 대해 세밀한 인용을 생성해요. 이 능력은 Command 모델 패밀리에 기본 제공됩니다.
다음 섹션들은 비스트리밍과 스트리밍 모드 모두에서 인용에 접근하는 방법을 설명해요.
비스트리밍(Non-streaming)
먼저, 도구와 관련 스키마를 정의합니다.
Cohere 플랫폼
PYTHON
# ! pip install -U cohere
import cohere
import json
co = cohere.ClientV2(
"COHERE_API_KEY"
) # Get your free API key here: https://dashboard.cohere.com/api-keys
프라이빗 배포(Private deployment)
PYTHON
# ! pip install -U cohere
import cohere
import json
co = cohere.ClientV2(
api_key="", # Leave this blank
base_url="<YOUR_DEPLOYMENT_URL>",
)
PYTHON
def get_weather(location):
temperature = {
"bern": "22°C",
"madrid": "24°C",
"brasilia": "28°C",
}
loc = location.lower()
if loc in temperature:
return [{"temperature": {loc: temperature[loc]}}]
return [{"temperature": {loc: "Unknown"}}]
functions_map = {"get_weather": get_weather}
tools = [
{
"type": "function",
"function": {
"name": "get_weather",
"description": "gets the weather of a given location",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "the location to get the weather, example: San Francisco.",
}
},
"required": ["location"],
},
},
}
]
다음으로, 도구 호출 및 실행 단계를 진행합니다.
PYTHON
messages = [
{
"role": "user",
"content": "What's the weather in Madrid and Brasilia?",
}
]
response = co.chat(
model="command-a-plus-05-2026", messages=messages, tools=tools
)
if response.message.tool_calls:
messages.append(response.message)
for tc in response.message.tool_calls:
tool_result = functions_map[tc.function.name](
**json.loads(tc.function.arguments)
)
tool_content = []
for data in tool_result:
tool_content.append(
{
"type": "document",
"document": {"data": json.dumps(data)},
}
)
messages.append(
{
"role": "tool",
"tool_call_id": tc.id,
"content": tool_content,
}
)
cURL
curl --request POST \
--url https://api.cohere.ai/v2/chat \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header "Authorization: bearer ***" \
--data '{
"model": "command-a-plus-05-2026",
"messages": [
{
"role": "user",
"content": "What'\''s the weather in Madrid and Brasilia?"
}
],
"tools": [
{
"type": "function",
"function": {
"name": "get_weather",
"description": "gets the weather of a given location",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "the location to get the weather, example: San Francisco."
}
},
"required": ["location"]
}
}
}
]
}'
비스트리밍 모드(chat로 모델 응답 생성)에서는 인용이 응답 객체의 message.citations 필드에 제공됩니다.
각 인용 객체에는 다음이 포함됩니다:
start및end: 소스를 인용하는 텍스트의 시작 및 끝 인덱스text: 그에 해당하는 텍스트 범위(span)sources: 참조하는 소스
PYTHON
response = co.chat(
model="command-a-plus-05-2026", messages=messages, tools=tools
)
messages.append(
{"role": "assistant", "content": response.message.content[0].text}
)
print(response.message.content[0].text)
for citation in response.message.citations:
print(citation, "\n")
cURL
curl --request POST \
--url https://api.cohere.ai/v2/chat \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header "Authorization: bearer ***" \
--data '{
"model": "command-a-plus-05-2026",
"messages": [
{
"role": "user",
"content": "What'\''s the weather in Madrid and Brasilia?"
},
{
"role": "assistant",
"tool_plan": "I will search for the weather in Madrid and Brasilia.",
"tool_calls": [
{
"id": "get_weather_14brd1n2kfqj",
"type": "function",
"function": {
"name": "get_weather",
"arguments": "{\"location\":\"Madrid\"}"
}
},
{
"id": "get_weather_vdr9cvj619fk",
"type": "function",
"function": {
"name": "get_weather",
"arguments": "{\"location\":\"Brasilia\"}"
}
}
]
},
{
"role": "tool",
"tool_call_id": "get_weather_14brd1n2kfqj",
"content": [
{
"type": "document",
"document": {
"data": "{\"temperature\": {\"madrid\": \"24°C\"}}"
}
}
]
},
{
"role": "tool",
"tool_call_id": "get_weather_vdr9cvj619fk",
"content": [
{
"type": "document",
"document": {
"data": "{\"temperature\": {\"brasilia\": \"28°C\"}}"
}
}
]
}
],
"tools": [
{
"type": "function",
"function": {
"name": "get_weather",
"description": "gets the weather of a given location",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "the location to get the weather, example: San Francisco."
}
},
"required": ["location"]
}
}
}
]
}'
예제 응답:
It is currently 24°C in Madrid and 28°C in Brasilia.
start=16 end=20 text='24°C' sources=[ToolSource(type='tool', id='get_weather_14brd1n2kfqj:0', tool_output={'temperature': '{"madrid":"24°C"}'})] type='TEXT_CONTENT'
start=35 end=39 text='28°C' sources=[ToolSource(type='tool', id='get_weather_vdr9cvj619fk:0', tool_output={'temperature': '{"brasilia":"28°C"}'})] type='TEXT_CONTENT'
스트리밍(Streaming)
스트리밍 시나리오(chat_stream으로 모델 응답 생성)에서는 인용이 citation-start 이벤트에 제공됩니다.
각 인용 객체는 비스트리밍 시나리오와 동일한 필드를 포함합니다.
PYTHON
response = co.chat_stream(
model="command-a-plus-05-2026", messages=messages, tools=tools
)
response_text = ""
citations = []
for chunk in response:
if chunk:
if chunk.type == "content-delta":
response_text += chunk.delta.message.content.text
print(chunk.delta.message.content.text, end="")
if chunk.type == "citation-start":
citations.append(chunk.delta.message.citations)
messages.append({"role": "assistant", "content": response_text})
for citation in citations:
print(citation, "\n")
cURL
curl --request POST \
--url https://api.cohere.ai/v2/chat \
--header 'accept: text/event-stream' \
--header 'content-type: application/json' \
--header "Authorization: bearer ***" \
--data '{
"model": "command-a-plus-05-2026",
"messages": [
{
"role": "user",
"content": "What'\''s the weather in Madrid and Brasilia?"
},
{
"role": "assistant",
"tool_plan": "I will search for the weather in Madrid and Brasilia.",
"tool_calls": [
{
"id": "get_weather_dkf0akqdazjb",
"type": "function",
"function": {
"name": "get_weather",
"arguments": "{\"location\":\"Madrid\"}"
}
},
{
"id": "get_weather_gh65bt2tcdy1",
"type": "function",
"function": {
"name": "get_weather",
"arguments": "{\"location\":\"Brasilia\"}"
}
}
]
},
{
"role": "tool",
"tool_call_id": "get_weather_dkf0akqdazjb",
"content": [
{
"type": "document",
"document": {
"data": "{\"temperature\": {\"madrid\": \"24°C\"}}"
}
}
]
},
{
"role": "tool",
"tool_call_id": "get_weather_gh65bt2tcdy1",
"content": [
{
"type": "document",
"document": {
"data": "{\"temperature\": {\"brasilia\": \"28°C\"}}"
}
}
]
}
],
"tools": [
{
"type": "function",
"function": {
"name": "get_weather",
"description": "gets the weather of a given location",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "the location to get the weather, example: San Francisco."
}
},
"required": ["location"]
}
}
}
],
"stream": true
}'
예제 응답:
It is currently 24°C in Madrid and 28°C in Brasilia.
start=16 end=20 text='24°C' sources=[ToolSource(type='tool', id='get_weather_dkf0akqdazjb:0', tool_output={'temperature': '{"madrid":"24°C"}'})] type='TEXT_CONTENT'
start=35 end=39 text='28°C' sources=[ToolSource(type='tool', id='get_weather_gh65bt2tcdy1:0', tool_output={'temperature': '{"brasilia":"28°C"}'})] type='TEXT_CONTENT'
문서 ID(Document ID)
도구 실행 단계에서 도구 결과를 전달할 때, document 객체의 id 필드에 사용자 지정 ID를 선택적으로 추가할 수 있어요. 이 ID는 엔드포인트가 인용 참조로 사용합니다.
id 필드를 제공하지 않으면 ID는 <tool_call_id>:<auto_generated_id> 형식으로 자동 생성됩니다. 예: get_weather_1byjy32y4hvq:0.
다음은 사용자 지정 ID를 사용하는 예시예요. 간결하게 하기 위해 사용자 쿼리, 도구 호출, 도구 결과가 이미 준비된 사전 정의된 messages 목록으로 시작하겠습니다.
PYTHON
# ! pip install -U cohere
import cohere
import json
co = cohere.ClientV2(
"COHERE_API_KEY"
) # Get your free API key here: https://dashboard.cohere.com/api-keys
messages = [
{
"role": "user",
"content": "What's the weather in Madrid and Brasilia?",
},
{
"role": "assistant",
"tool_plan": "I will search for the weather in Madrid and Brasilia.",
"tool_calls": [
{
"id": "get_weather_dkf0akqdazjb",
"type": "function",
"function": {
"name": "get_weather",
"arguments": '{"location":"Madrid"}',
},
},
{
"id": "get_weather_gh65bt2tcdy1",
"type": "function",
"function": {
"name": "get_weather",
"arguments": '{"location":"Brasilia"}',
},
},
],
},
{
"role": "tool",
"tool_call_id": "get_weather_dkf0akqdazjb",
"content": [
{
"type": "document",
"document": {
"data": '{"temperature": {"madrid": "24°C"}}',
"id": "1",
},
}
],
},
{
"role": "tool",
"tool_call_id": "get_weather_gh65bt2tcdy1",
"content": [
{
"type": "document",
"document": {
"data": '{"temperature": {"brasilia": "28°C"}}',
"id": "2",
},
}
],
},
]
문서 ID가 제공되면 인용은 이 ID들을 사용해 문서를 참조합니다.
PYTHON
response = co.chat(
model="command-a-plus-05-2026", messages=messages, tools=tools
)
print(response.message.content[0].text)
for citation in response.message.citations:
print(citation, "\n")
cURL
curl --request POST \
--url https://api.cohere.ai/v2/chat \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header "Authorization: bearer ***" \
--data '{
"model": "command-a-plus-05-2026",
"messages": [
{
"role": "user",
"content": "What'\''s the weather in Madrid and Brasilia?"
},
{
"role": "assistant",
"tool_plan": "I will search for the weather in Madrid and Brasilia.",
"tool_calls": [
{
"id": "get_weather_dkf0akqdazjb",
"type": "function",
"function": {
"name": "get_weather",
"arguments": "{\"location\":\"Madrid\"}"
}
},
{
"id": "get_weather_gh65bt2tcdy1",
"type": "function",
"function": {
"name": "get_weather",
"arguments": "{\"location\":\"Brasilia\"}"
}
}
]
},
{
"role": "tool",
"tool_call_id": "get_weather_dkf0akqdazjb",
"content": [
{
"type": "document",
"document": {
"data": "{\"temperature\": {\"madrid\": \"24°C\"}}",
"id": "1"
}
}
]
},
{
"role": "tool",
"tool_call_id": "get_weather_gh65bt2tcdy1",
"content": [
{
"type": "document",
"document": {
"data": "{\"temperature\": {\"brasilia\": \"28°C\"}}",
"id": "2"
}
}
]
}
],
"tools": [
{
"type": "function",
"function": {
"name": "get_weather",
"description": "gets the weather of a given location",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "the location to get the weather, example: San Francisco."
}
},
"required": ["location"]
}
}
}
]
}'
인용의 id 필드가 document 객체의 ID를 참조하는 것에 주목하세요.
예제 응답:
It's 24°C in Madrid and 28°C in Brasilia.
start=5 end=9 text='24°C' sources=[ToolSource(type='tool', id='1', tool_output={'temperature': '{"madrid":"24°C"}'})] type='TEXT_CONTENT'
start=24 end=28 text='28°C' sources=[ToolSource(type='tool', id='2', tool_output={'temperature': '{"brasilia":"28°C"}'})] type='TEXT_CONTENT'
대조적으로, ID가 제공되지 않은 경우의 인용 예시는 다음과 같아요.
예제 응답:
It is currently 24°C in Madrid and 28°C in Brasilia.
start=16 end=20 text='24°C' sources=[ToolSource(type='tool', id='get_weather_dkf0akqdazjb:0', tool_output={'temperature': '{"madrid":"24°C"}'})] type='TEXT_CONTENT'
start=35 end=39 text='28°C' sources=[ToolSource(type='tool', id='get_weather_gh65bt2tcdy1:0', tool_output={'temperature': '{"brasilia":"28°C"}'})] type='TEXT_CONTENT'
인용 모드(Citation modes)
스트리밍 모드에서 도구 사용을 실행할 때 인용이 생성되고 제시되는 방식을 구성할 수 있어요. 지연 시간과 정밀도 요구에 따라 빠른 인용(fast citations) 또는 정확한 인용(accurate citations) 중에서 선택할 수 있습니다.
정확한 인용(Accurate citations)
모델이 먼저 답변을 생성하고, 전체 응답이 생성된 후 응답 텍스트의 특정 구간에 매핑되는 인용을 제공해요. 이 접근 방식은 약간 더 높은 지연 시간이 발생할 수 있지만, 인용 인덱스가 모델 답변의 최종 텍스트 구간과 더 정밀하게 정렬되도록 보장합니다.
이것이 기본 옵션이며, API 호출에 citation_options={"mode": "accurate"} 인자를 추가하면 명시적으로 지정할 수도 있어요.
다음은 위와 동일한 사전 정의된 messages 목록을 사용하는 예시입니다.
citation_options 모드를 accurate로 설정하면, 전체 응답이 생성된 후에 인용을 얻을 수 있어요.
PYTHON
# ! pip install -U cohere
import cohere
import json
co = cohere.ClientV2(
"COHERE_API_KEY"
) # Get your free API key here: https://dashboard.cohere.com/api-keys
response = co.chat_stream(
model="command-a-plus-05-2026",
messages=messages,
tools=tools,
citation_options={"mode": "accurate"},
)
response_text = ""
citations = []
for chunk in response:
if chunk:
if chunk.type == "content-delta":
response_text += chunk.delta.message.content.text
print(chunk.delta.message.content.text, end="")
if chunk.type == "citation-start":
citations.append(chunk.delta.message.citations)
print("\n")
for citation in citations:
print(citation, "\n")
cURL
curl --request POST \
--url https://api.cohere.ai/v2/chat \
--header 'accept: text/event-stream' \
--header 'content-type: application/json' \
--header "Authorization: bearer ***" \
--data '{
"model": "command-a-plus-05-2026",
"messages": [
{
"role": "user",
"content": "What'\''s the weather in Madrid and Brasilia?"
},
{
"role": "assistant",
"tool_plan": "I will search for the weather in Madrid and Brasilia.",
"tool_calls": [
{
"id": "get_weather_dkf0akqdazjb",
"type": "function",
"function": {
"name": "get_weather",
"arguments": "{\"location\":\"Madrid\"}"
}
},
{
"id": "get_weather_gh65bt2tcdy1",
"type": "function",
"function": {
"name": "get_weather",
"arguments": "{\"location\":\"Brasilia\"}"
}
}
]
},
{
"role": "tool",
"tool_call_id": "get_weather_dkf0akqdazjb",
"content": [
{
"type": "document",
"document": {
"data": "{\"temperature\": {\"madrid\": \"24°C\"}}",
"id": "1"
}
}
]
},
{
"role": "tool",
"tool_call_id": "get_weather_gh65bt2tcdy1",
"content": [
{
"type": "document",
"document": {
"data": "{\"temperature\": {\"brasilia\": \"28°C\"}}",
"id": "2"
}
}
]
}
],
"tools": [
{
"type": "function",
"function": {
"name": "get_weather",
"description": "gets the weather of a given location",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "the location to get the weather, example: San Francisco."
}
},
"required": ["location"]
}
}
}
],
"citation_options": {
"mode": "accurate"
},
"stream": true
}'
예제 응답:
It is currently 24°C in Madrid and 28°C in Brasilia.
start=16 end=20 text='24°C' sources=[ToolSource(type='tool', id='1', tool_output={'temperature': '{"madrid":"24°C"}'})] type='TEXT_CONTENT'
start=35 end=39 text='28°C' sources=[ToolSource(type='tool', id='2', tool_output={'temperature': '{"brasilia":"28°C"}'})] type='TEXT_CONTENT'
빠른 인용(Fast citations)
모델이 응답을 생성하면서 인라인으로 인용을 생성해요. 스트리밍 모드에서는 모델이 특정 외부 컨텍스트를 사용하는 바로 그 순간에 주입된 인용을 볼 수 있어요. 이 접근 방식은 인용 정확도에서 약간 덜 정밀해지는 대가로 즉각적인 추적 가능성(traceability)을 제공합니다.
API 호출에 citation_options={"mode": "fast"} 인자를 추가하면 지정할 수 있어요.
citation_options 모드를 fast로 설정하면, 모델이 응답을 생성하는 동안 인라인으로 인용을 얻을 수 있어요.
PYTHON
response = co.chat_stream(
model="command-a-plus-05-2026",
messages=messages,
tools=tools,
citation_options={"mode": "fast"},
)
response_text = ""
for chunk in response:
if chunk:
if chunk.type == "content-delta":
response_text += chunk.delta.message.content.text
print(chunk.delta.message.content.text, end="")
if chunk.type == "citation-start":
print(
f" [{chunk.delta.message.citations.sources[0].id}]",
end="",
)
cURL
curl --request POST \
--url https://api.cohere.ai/v2/chat \
--header 'accept: text/event-stream' \
--header 'content-type: application/json' \
--header "Authorization: bearer ***" \
--data '{
"model": "command-a-plus-05-2026",
"messages": [
{
"role": "user",
"content": "What'\''s the weather in Madrid and Brasilia?"
},
{
"role": "assistant",
"tool_plan": "I will search for the weather in Madrid and Brasilia.",
"tool_calls": [
{
"id": "get_weather_dkf0akqdazjb",
"type": "function",
"function": {
"name": "get_weather",
"arguments": "{\"location\":\"Madrid\"}"
}
},
{
"id": "get_weather_gh65bt2tcdy1",
"type": "function",
"function": {
"name": "get_weather",
"arguments": "{\"location\":\"Brasilia\"}"
}
}
]
},
{
"role": "tool",
"tool_call_id": "get_weather_dkf0akqdazjb",
"content": [
{
"type": "document",
"document": {
"data": "{\"temperature\": {\"madrid\": \"24°C\"}}",
"id": "1"
}
}
]
},
{
"role": "tool",
"tool_call_id": "get_weather_gh65bt2tcdy1",
"content": [
{
"type": "document",
"document": {
"data": "{\"temperature\": {\"brasilia\": \"28°C\"}}",
"id": "2"
}
}
]
}
],
"tools": [
{
"type": "function",
"function": {
"name": "get_weather",
"description": "gets the weather of a given location",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "the location to get the weather, example: San Francisco."
}
},
"required": ["location"]
}
}
}
],
"citation_options": {
"mode": "fast"
},
"stream": true
}'
예제 응답:
It is currently 24°C [1] in Madrid and 28°C [2] in Brasilia.