Предупреждение
Ссылки являются экспериментальными. Имя параметра, полезные данные события и охват поставщика могут измениться в будущем выпуске.
Как работают ссылки
Ссылки создаются поставщиком модели, а не пакетом SDK. Поток состоит из трех частей:
- Приложение предоставляет доступный материал, например вложение документа или результат средства, который содержит исходное содержимое.
- Среда выполнения помечает этот материал как доступный на проводе при
enableCitationsвключении. Для моделей Anthropic файлы отправляются в видеdocumentблоков с включенными ссылками. - Модель возвращает метаданные ссылки, а среда выполнения нормализует ее в объект, не зависящий
citationsот поставщика, на последнемassistant.messageсобытии.
Поддержка поставщика ограничена.
provider Поле для каждой исходной записи, из которой была получена ссылка:
| Значение провайдера | Meaning |
|---|---|
anthropic | Цитата, созданная ответом модели Anthropic (Claude) |
openai | Ссылка, созданная ответом модели OpenAI |
client | Цитата, синтезируемая средой выполнения из выходных данных средства |
Примечание.
enableCitations Включение не гарантирует, что ответ содержит ссылки. Модели выдают их только в том случае, если ответ находится в доступном исходном материале. Всегда рассматривать citations поле как необязательное.
Включение ссылок на сеанс
Задайте параметр для создания сеанса и снова установите его в возобновлении, если вы хотите, чтобы ссылки после перезапуска.
const session = await client.createSession({
onPermissionRequest: approveAll,
enableCitations: true,
});
const resumed = await client.resumeSession(session.sessionId, {
onPermissionRequest: approveAll,
enableCitations: true,
});
session = await client.create_session(
on_permission_request=PermissionHandler.approve_all,
enable_citations=True,
)
resumed = await client.resume_session(
session.session_id,
on_permission_request=PermissionHandler.approve_all,
enable_citations=True,
)
session, err := client.CreateSession(ctx, &copilot.SessionConfig{
OnPermissionRequest: copilot.PermissionHandler.ApproveAll,
EnableCitations: copilot.Bool(true),
})
resumed, err := client.ResumeSession(ctx, session.SessionID, &copilot.ResumeSessionConfig{
OnPermissionRequest: copilot.PermissionHandler.ApproveAll,
EnableCitations: copilot.Bool(true),
})
var session = await client.CreateSessionAsync(new SessionConfig
{
OnPermissionRequest = PermissionHandler.ApproveAll,
EnableCitations = true,
});
var resumed = await client.ResumeSessionAsync(session.SessionId, new ResumeSessionConfig
{
OnPermissionRequest = PermissionHandler.ApproveAll,
EnableCitations = true,
});
CopilotSession session = client
.createSession(new SessionConfig()
.setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
.setEnableCitations(true))
.get();
CopilotSession resumed = client
.resumeSession(session.getSessionId(), new ResumeSessionConfig()
.setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
.setEnableCitations(true))
.get();
let session = client
.create_session(
SessionConfig::new()
.approve_all_permissions()
.with_enable_citations(true),
)
.await?;
let resumed = client
.resume_session(
ResumeSessionConfig::new(session.id().clone())
.approve_all_permissions()
.with_enable_citations(true),
)
.await?;
Чтение ссылок из сообщений помощника
Ссылки приходят на окончательное assistant.message событие, а не на assistant.message_delta события. Дождитесь окончательного сообщения перед отображением исходных маркеров.
session.on((event) => {
if (event.type !== "assistant.message" || !event.data.citations) {
return;
}
const { sources, spans } = event.data.citations;
const sourceById = new Map(sources.map((source) => [source.id, source]));
for (const span of spans) {
const quoted = event.data.content.slice(span.startIndex, span.endIndex);
for (const reference of span.references) {
const source = sourceById.get(reference.sourceId);
const label = source?.title ?? source?.url ?? source?.path ?? source?.id;
console.log(`"${quoted}" — ${label}`);
}
}
});
from copilot.session_events import SessionEventType
def utf16_slice(text: str, start: int, end: int) -> str:
"""Slice by UTF-16 code units, which is how span offsets are measured."""
units = text.encode("utf-16-le")
return units[start * 2 : end * 2].decode("utf-16-le")
def handle(event):
if event.type != SessionEventType.ASSISTANT_MESSAGE or not event.data.citations:
return
sources = {source.id: source for source in event.data.citations.sources}
for span in event.data.citations.spans:
quoted = utf16_slice(event.data.content, span.start_index, span.end_index)
for reference in span.references:
source = sources[reference.source_id]
label = source.title or source.url or source.path or source.id
print(f'"{quoted}" — {label}')
session.on(handle)
// import "unicode/utf16"
session.On(func(event copilot.SessionEvent) {
d, ok := event.Data.(*copilot.AssistantMessageData)
if !ok || d.Citations == nil {
return
}
sources := map[string]copilot.CitationSource{}
for _, source := range d.Citations.Sources {
sources[source.ID] = source
}
// Span offsets are UTF-16 code units, so index the UTF-16 view of the content.
units := utf16.Encode([]rune(d.Content))
for _, span := range d.Citations.Spans {
quoted := string(utf16.Decode(units[span.StartIndex:span.EndIndex]))
for _, reference := range span.References {
source := sources[reference.SourceID]
label := source.ID
switch {
case source.Title != nil:
label = *source.Title
case source.URL != nil:
label = *source.URL
case source.Path != nil:
label = *source.Path
}
fmt.Printf("%q — %s\n", quoted, label)
}
}
})
session.On<SessionEvent>(evt =>
{
if (evt is not AssistantMessageEvent message || message.Data.Citations is null)
{
return;
}
var sources = message.Data.Citations.Sources.ToDictionary(source => source.Id);
foreach (var span in message.Data.Citations.Spans)
{
var quoted = message.Data.Content[(int)span.StartIndex..(int)span.EndIndex];
foreach (var reference in span.References)
{
var source = sources[reference.SourceId];
var label = source.Title ?? source.Url ?? source.Path ?? source.Id;
Console.WriteLine($"\"{quoted}\" — {label}");
}
}
});
session.on(AssistantMessageEvent.class, event -> {
Citations citations = event.getData().citations();
if (citations == null) {
return;
}
Map<String, CitationSource> sources = citations.sources().stream()
.collect(Collectors.toMap(CitationSource::id, source -> source));
for (CitationSpan span : citations.spans()) {
String quoted = event.getData().content()
.substring(span.startIndex().intValue(), span.endIndex().intValue());
for (CitationReference reference : span.references()) {
CitationSource source = sources.get(reference.sourceId());
String label = source.title() != null ? source.title()
: source.url() != null ? source.url()
: source.path() != null ? source.path()
: source.id();
System.out.printf("\"%s\" — %s%n", quoted, label);
}
}
});
use github_copilot_sdk::session_events::AssistantMessageData;
use std::collections::HashMap;
let mut events = session.subscribe();
while let Ok(event) = events.recv().await {
if event.event_type != "assistant.message" {
continue;
}
let Some(data) = event.typed_data::<AssistantMessageData>() else {
continue;
};
let Some(citations) = data.citations.as_ref() else {
continue;
};
let sources: HashMap<&str, _> = citations
.sources
.iter()
.map(|source| (source.id.as_str(), source))
.collect();
// Span offsets are UTF-16 code units, so index the UTF-16 view of the content.
let units: Vec<u16> = data.content.encode_utf16().collect();
for span in &citations.spans {
let quoted = String::from_utf16_lossy(
&units[span.start_index as usize..span.end_index as usize],
);
for reference in &span.references {
let Some(source) = sources.get(reference.source_id.as_str()) else {
continue;
};
let label = source
.title
.as_deref()
.or(source.url.as_deref())
.or(source.path.as_deref())
.unwrap_or(source.id.as_str());
println!("\"{quoted}\" — {label}");
}
}
}
Справочник по полезным данным ссылки на ссылки
Объект citations отделяет дедупликированные источники от диапазонов, ссылающихся на них, поэтому источник, цитируемый пять раз, отображается один раз в sources.
| Тип | Поле | Description |
|---|---|---|
Citations | sources | Дедупликированный набор источников, на которые ссылается диапазон ссылок |
Citations | spans | Диапазоны созданных текстовых аннотированных с поддержкой источников |
CitationSource | id | Стабильный идентификатор с заданной областью действия, на который ссылается Citation |
CitationSource | provider | Система, которая произвела ссылку: anthropic, openaiили client |
CitationSource | title? | Читаемый человеком заголовок источника |
CitationSource | url? | URL-адрес источника, когда он является веб-ресурсом |
CitationSource | path? | Путь к файлу относительно корневого каталога рабочей области агента, когда источник является файлом |
CitationSpan | startIndex | Смещение запуска в окончательном содержимом сообщения (единицы кода UTF-16, отсчитываемые от нуля) |
CitationSpan | endIndex | Завершение смещения в окончательном содержимом сообщения (единицы кода UTF-16, отсчитываемые от нуля, эксклюзивные) |
CitationSpan | references | Источники, поддерживающие этот диапазон |
CitationReference | sourceId | |
CitationSource Идентификатор этих ссылочных точек | ||
CitationReference | citedText? | Точный текст из источника, поддерживающего диапазон, когда модель предоставляет ее. |
CitationReference | location? | Расположение в источнике, поддерживающее диапазон |
CitationReference | providerMetadata? | Данные корреляции, передаваемые через непрозрачные данные корреляции поставщика |
Совет
Смещения диапазона измеряются в единицах кода UTF-16 по последней content строке. Строки TypeScript, Java и .NET уже являются UTF-16, поэтому их можно срезать напрямую. Python строки индексируются точкой кода Юникода и строками Go и Rust являются UTF-8, поэтому перед фрагментированием преобразуйте содержимое в единицы кода UTF-16, как показано выше.
Расположения ссылок
CitationReference.location является дискриминированным объединением, ключом к type:
| Тип местоположения | Fields | Использование |
|---|---|---|
char | ||
startIndex, endIndex | Диапазон символов в исходном тексте | |
page | ||
startPage, endPage | Диапазон страниц в документе с разбивкой на страницы | |
block | ||
startBlock, endBlock | Диапазон блоков содержимого в структурированном документе |
Предоставление доступных источников
Ссылки нуждаются в исходном материале, который может атрибутом модели. Существует два способа его предоставления.
Присоединение документов к сообщению
Если ссылки включены и сеанс использует поставщик Anthropic, вложения файлов отправляются в виде document блоков с включенными ссылками, поэтому модель может ссылаться на фрагменты из них.
await session.sendAndWait({
prompt: "Summarize the attached PDF and cite the passages you used.",
attachments: [
{
type: "blob",
data: pdfBase64,
displayName: "quarterly-report.pdf",
mimeType: "application/pdf",
},
],
});
См. раздел AUTOTITLE для API вложений и file``blob фигуры вложений.
Возврат доступных источников из средства
Результаты инструментов содержат экспериментальный citableSources массив. Каждая запись предоставляет, к которым может ссылаться content модель, id а также необязательный title, urlи path. Эти источники сохраняются с результатом средства, поэтому они выживают возобновление сеанса, а ссылки, созданные из них, помечены поставщиком client .
Ограничения
- Ссылки являются экспериментальными в каждом пакете SDK и не охватываются гарантиями совместимости.
- Покрытие зависит от поставщика модели. Сеанс, настроенный для поставщика без поддержки ссылок, не выдает
citationsполезных данных. - Ссылки присутствуют только в последнем
assistant.messageсобытии, поэтому потребители потоковой передачи не могут отображать их в середине ответа. - Общедоступный код и ссылки на дублирование IP-адресов не являются частью этой поверхности.
Дополнительные материалы
- События потоковых сессий: подписка на события сеанса и узкие типы событий
- Ввод изображения: присоединение файлов и BLOB-объектов в памяти к сообщению
- Возобновление сессии и сохранение: возобновление сеансов и повторное применение параметров сеанса
- Совместимость SDK и CLI: матрица функций ПАКЕТА SDK и CLI