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