/
model_card.proto
281 lines (221 loc) · 8 KB
/
model_card.proto
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
syntax = "proto2";
package third_party.py.model_card_toolkit.proto;
// The information about owners of a model.
// The next tag number is 3.
message Owner {
// The name of the model owner.
optional string name = 1;
// The contact information for the model owner or owners.
optional string contact = 2;
}
// The information about verions of a model.
// If there are multiple versions of the model, or there may be in the future,
// it’s useful for your audience to know which version of the model is discussed
// in the Model Card. If there are previous versions of this model, briefly
// describe how this version is different. If no more than one version of the
// model will be released, this field may be omitted.
// The next tag number is 4.
message Version {
// The name of the version.
optional string name = 1;
// The date this version was released.
optional string date = 2;
// The changes from the previous version.
optional string diff = 3;
}
// The next tag number is 3.
message License {
oneof type {
// A standard SPDX license identifier (https://spdx.org/licenses/), or
// "proprietary" for an unlicensed module.
string identifier = 1;
// The text of a custom license.
string custom_text = 2;
}
}
message Reference {
// A reference to a resource.
optional string reference = 1;
}
// A citation for the model.
// The next tag number is 3.
message Citation {
// The citation style.
optional string style = 1;
// The citation content.
optional string citation = 2;
}
// This section provides a general, high-level description of the model.
// The next tag number is 10.
message ModelDetails {
// The name of the model.
optional string name = 1;
// A brief, one-line description of the model.
optional string overview = 2;
// A more thorough description of the model and its usage.
optional string documentation = 3;
// The individuals or teams who own the model.
repeated Owner owners = 4;
// The version of the model.
optional Version version = 5;
// The license information for the model.
repeated License licenses = 6;
// Provide any additional references the reader may need.
repeated Reference references = 7;
// How should the model be cited?
repeated Citation citations = 8;
// Where is this model stored?
optional string path = 9;
}
// A named inline plot.
// The next tag number is 3.
message Graphic {
// The name of the graphic.
optional string name = 1;
// The image, encoded as a base64 string.
optional string image = 2;
}
// A collection of graphics.
// Each graphic in the collection field has both a name and an image.
// The next tag number is 3.
message GraphicsCollection {
// A description of the Graphics collection.
optional string description = 1;
// A collection of graphics.
repeated Graphic collection = 2;
}
// Sensitive data, such as PII (personally-identifiable information).
// The next tag number is 2.
message SensitiveData {
// A description of any sensitive data that may be present in a dataset.
// Be sure to note PII information such as names, addresses, phone numbers,
// etc. Preferably, such info should be scrubbed from a dataset if possible.
// Note that even non-identifying information, such as zip code, age, race,
// and gender, can be used to identify individuals when aggregated. Please
// describe any such fields here.
repeated string sensitive_data = 1;
}
// Provide some information about a dataset used to generate a model.
// The next tag number is 6.
message Dataset {
// The name of the dataset.
optional string name = 1;
// A link to the dataset.
optional string link = 2;
// Does this dataset contain any human, PII, or sensitive data?
optional SensitiveData sensitive = 3;
// Visualizations of the dataset.
optional GraphicsCollection graphics = 4;
// A description of the dataset. Can describe size of dataset, whether it's
// used for training, testing, or validation, etc.
optional string description = 5;
}
// A generic key-value pair.
message KeyVal {
optional string key = 1;
optional string value = 2;
}
// Parameters for construction of the model.
// The next tag number is 7.
message ModelParameters {
// Specifies the architecture of your model.
optional string model_architecture = 1;
// Specifies the datasets used to train and evaluate your model.
repeated Dataset data = 2;
// Describes the data format for inputs to your model.
optional string input_format = 3;
repeated KeyVal input_format_map = 5;
// Describes the data format for outputs from your model.
optional string output_format = 4;
repeated KeyVal output_format_map = 6;
}
// The confidence interval of the metric.
message ConfidenceInterval {
// The lower bound of performance metric.
optional string lower_bound = 1;
// The upper bound of the performance metric.
optional string upper_bound = 2;
}
// The details of the performance metric.
message PerformanceMetric {
// TODO(b/179415408): revist the design the of message
// The following fields are EXPERIMENTAL and introduced for migration purpose.
// For proto users, please do not rely on the fields.
// The type of performance metric.
optional string type = 1;
// The value of the performance metric.
optional string value = 2;
// The name of the slice this metric was computed on.
// By default, assume this metric is not sliced.
optional string slice = 3;
// The confidence interval of the metric.
optional ConfidenceInterval confidence_interval = 4;
}
// The quantitative analysis of a model.
// The next tag number is 3.
message QuantitativeAnalysis {
// The performance metrics being reported.
repeated PerformanceMetric performance_metrics = 1;
// A collection of visualizations of model performance.
optional GraphicsCollection graphics = 2;
}
// A type of user for a model.
message User {
// A description of a user.
optional string description = 1;
}
// A type of use case for a model.
message UseCase {
// A description of a use case.
optional string description = 1;
}
// A limitation a model.
message Limitation {
// A description of the limitation.
optional string description = 1;
}
// A tradeoff for a model.
message Tradeoff {
// A description of the tradeoff.
optional string description = 1;
}
// Information about risks involved when using the model.
// The next tag number is 3.
message Risk {
// The name of the risk.
optional string name = 1;
// A mitigation strategy that you've implemented, or one you suggest to users.
optional string mitigation_strategy = 2;
}
// Considerations related to model construction, training, and application.
// The considerations section includes qualitative information about your model,
// including some analysis of its risks and limitations. As such, this section
// usually requires careful consideration, and conversations with many relevant
// stakeholders, including other model developers, dataset producers, and
// downstream users likely to interact with your model, or be affected by its
// outputs.
// The next tag number is 6.
message Considerations {
// Who are the intended users of the model?
repeated User users = 1;
// What are the intended use cases of the model?
repeated UseCase use_cases = 2;
// What are the known limitations of the model?
repeated Limitation limitations = 3;
// What are the known accuracy/performance tradeoffs for the model?
repeated Tradeoff tradeoffs = 4;
// What are the ethical risks involved in application of this model?
repeated Risk ethical_considerations = 5;
}
// Fields used to generate the Model Card.
// The next tag number is 5.
message ModelCard {
// Descriptive metadata for the model.
optional ModelDetails model_details = 1;
// Technical metadata for the model.
optional ModelParameters model_parameters = 2;
// Quantitative analysis of model performance.
optional QuantitativeAnalysis quantitative_analysis = 3;
// Any considerations related to model construction, training, and application
optional Considerations considerations = 4;
}